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

package/build/compiler.mjs

@@ -16,7 +16,7 @@ import {withSourceMaps,configureSourceMaps,inlineSourceMap} from './source-maps.
 import { optimizeImportsPlugins } from './optimize-imports.mjs';
 import {recordBuildAnalysis} from './analyze.mjs';
 import {recordDevDependencies,developmentDependencies,developmentStylePlans,developmentStyleDependencies,developmentModules} from './dev-dependencies.mjs';
-import {normalizeReactCompilerConfig,REACT_COMPILER_VERSION} from './react-compiler.mjs';
+import {normalizeReactCompilerConfig,reactCompilerVersion} from './react-compiler.mjs';
 import {withReactCompilerReporting,configureReactCompilerReporting,withReactCompilerGraph,recordReactCompilerGraph} from './react-compiler-report.mjs';
 import {withCompilationGraphCacheReporting,cachedGraphBuild} from './compilation-cache.mjs';
 export {reactCompilerReport} from './react-compiler-report.mjs';
@@ -27,7 +27,7 @@ const compilation = new AsyncLocalStorage();
 export const withCompilation = callback => withCompilationGraphCacheReporting(()=>withReactCompilerReporting(()=>withSourceMaps(()=>compilation.run({ targets: new Map(), loaded: new Map() }, callback))));
 export function configureCompiler(options) {
   Object.assign(compilation.getStore() || {}, options);configureSourceMaps(options.dev || options.config?.productionBrowserSourceMaps);
-  configureReactCompilerReporting({...options,config:{reactCompiler:options.config?.reactCompiler ? normalizeReactCompilerConfig(options.config.reactCompiler) : false},compilerVersion:REACT_COMPILER_VERSION});
+  configureReactCompilerReporting({...options,config:{reactCompiler:options.config?.reactCompiler ? normalizeReactCompilerConfig(options.config.reactCompiler) : false},compilerVersion:reactCompilerVersion(options.config?.reactCompiler,options.root)});
 }
 export const buildAnalysisRecords=()=>compilation.getStore()?.analysis;
 export const buildAnalysisRoutes=()=>compilation.getStore()?.analysisRoutes;
@@ -145,18 +145,19 @@ export async function validateCompilerConfig(config, root, {dev=false,edge=false
   const state={config,root,dev,buildId:'prnext-check',targets:new Map()};
   for (const target of ['node','browser',...(edge?['edge']:[])]) await targetConfig(state,target);
 }
-export async function build(options) {
+export async function build(options, { role = 'main' } = {}) {
+  if (role !== 'main' && role !== 'styles') throw new TypeError('Invalid compiler graph role');
   const state=compilation.getStore();
   const target=options.define?.['process.env.NEXT_RUNTIME']==='"edge"'?'edge':options.platform==='browser'?'browser':'node';
   return withReactCompilerGraph(target,async()=>{
-    const result=await compileGraph(options);
+    const result=await compileGraph(options,role);
     recordReactCompilerGraph(result);
     recordBuildAnalysis(state,options,result);
     recordDevDependencies(state,options,result);
     return result;
   });
 }
-async function compileGraph(options) {
+async function compileGraph(options,role) {
   const state = compilation.getStore();
   // The transform is captured by the framework's per-build callbacks. Give both
   // esbuild and the webpack bridge a new graph identity when its options change,
@@ -164,7 +165,7 @@ async function compileGraph(options) {
   // no hooks or runtime output and leaves the opt-out graph exactly as before.
   if ((options.plugins || []).some(plugin => framework.test(plugin.name)) && state?.config?.reactCompiler) {
     const settings=normalizeReactCompilerConfig(state.config.reactCompiler);
-    const fingerprint=createHash('sha256').update(JSON.stringify([REACT_COMPILER_VERSION,settings])).digest('hex').slice(0,24);
+    const fingerprint=createHash('sha256').update(JSON.stringify([reactCompilerVersion(settings,state.root),settings])).digest('hex').slice(0,24);
     options={...options,plugins:[...options.plugins,{name:'prnext-react-compiler-'+fingerprint,setup(){}}]};
   }
   if ((options.plugins || []).some(plugin => framework.test(plugin.name))) options = { ...options, plugins: optimizeImportsPlugins(options.plugins, state?.config?.experimental?.optimizePackageImports) };
@@ -183,7 +184,7 @@ async function compileGraph(options) {
   // Runtime vendor bundles are framework-owned, not project webpack targets.
   const projectGraph = (options.plugins || []).some(plugin => framework.test(plugin.name));
   if (projectGraph && state?.tsconfig) options = { ...options, tsconfig: state.tsconfig };
-  const nativeCompile = input => state?.incremental && (projectGraph || !input.plugins?.length) ? incrementalBuild(input,{root:state.root,stage:state.stage,group:projectGraph?'project':'auxiliary',run:callback=>compilation.run(state,callback)}) : esbuild(input);
+  const nativeCompile = input => state?.incremental && (projectGraph || !input.plugins?.length) ? incrementalBuild(input,{root:state.root,stage:state.stage,group:projectGraph?'project':'auxiliary',role:projectGraph?role:'auxiliary',run:callback=>compilation.run(state,callback)}) : esbuild(input);
   const compile = input => state?.root && state?.stage ? cachedGraphBuild(input,state,nativeCompile) : nativeCompile(input);
   if (!(state?.config?.webpack || Object.keys(state?.config?.turbopack?.rules || {}).length) || !projectGraph) return compile(options);
   const target = options.define?.['process.env.NEXT_RUNTIME'] === '"edge"' ? 'edge' : options.platform === 'browser' ? 'browser' : 'node';

package/build/config.mjs

@@ -25,6 +25,8 @@ import {validatePrerenderConfig} from './prerender-config.mjs';
 import {validateHtmlOnly} from './html-only-config.mjs';
 import { validateProxyBodySize } from './proxy-body-config.mjs';
 import { normalizeReactCompilerConfig } from './react-compiler.mjs';
+import {validateCompilationCache} from './compilation-storage.mjs';
+import {validateServerConfig} from './server-config.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const configName = /^(?:next|prnext)\.config\.(?:js|mjs|cjs|ts)$/;
@@ -37,6 +39,8 @@ supported.add('workerMemory');
 supported.add('workerRetirement');
 supported.add('workerPreload');
 supported.add('deploymentRetention');
+supported.add('compilationCache');
+supported.add('server');
 supported.add('prerender');
 supported.add('htmlOnly');
 supported.add('cssEngine');
@@ -107,6 +111,7 @@ export function validateProjectConfig(input, filename = 'project config') {
   config.workerRetirement = validateWorkerRetirement(config.workerRetirement);
   config.workerPreload=validateWorkerPreload(config.workerPreload);
   config.deploymentRetention=validateDeploymentRetention(config.deploymentRetention);
+  config.compilationCache=validateCompilationCache(config.compilationCache);
   config.prerender=validatePrerenderConfig(config.prerender);
   config.htmlOnly=validateHtmlOnly(config.htmlOnly);
   config.cssEngine ??= 'auto';
@@ -127,6 +132,7 @@ export function validateProjectConfig(input, filename = 'project config') {
   }
   if (config.webpack !== undefined && typeof config.webpack !== 'function') throw new TypeError('webpack must be a configuration function');
   config.turbopack = validateTurbopack(config.turbopack);
+  config.server = validateServerConfig(config.server);
   config.i18n = validateI18n(config.i18n);
   if (config.i18n && config.output === 'export') throw new Error("i18n and output: 'export' cannot be combined; use explicit locale routes for static exports");
   validateStandaloneConfig(config);
@@ -164,11 +170,28 @@ export function validateProjectConfig(input, filename = 'project config') {
   if (config.sassOptions !== undefined && (!config.sassOptions || typeof config.sassOptions !== 'object' || Array.isArray(config.sassOptions))) throw new Error(`${filename}: sassOptions must be an object.`);
   if (!config.experimental || typeof config.experimental !== 'object' || Array.isArray(config.experimental)) throw new Error(`${filename}: experimental must be an object.`);
   for (const key of Object.keys(config.experimental)) {
-    if (!['nextScriptWorkers', 'serverActions', 'optimizePackageImports', 'proxyClientMaxBodySize'].includes(key)) throw new Error(`${filename}: experimental.${key} is not supported by PRNext. It cannot be silently ignored.`);
+    if (!['nextScriptWorkers', 'serverActions', 'optimizePackageImports', 'proxyClientMaxBodySize', 'lazyDynamicImports', 'streamingRequestBodies', 'nativePprShell', 'parallelBuilds'].includes(key)) throw new Error(`${filename}: experimental.${key} is not supported by PRNext. It cannot be silently ignored.`);
   }
   const nextScriptWorkers = config.experimental.nextScriptWorkers === undefined ? false : config.experimental.nextScriptWorkers;
   if (typeof nextScriptWorkers !== 'boolean') throw new Error(`${filename}: experimental.nextScriptWorkers must be a boolean.`);
-  config.experimental = { nextScriptWorkers, serverActions: validateServerActions(config.experimental.serverActions), optimizePackageImports: validateOptimizePackageImports(config.experimental.optimizePackageImports), proxyClientMaxBodySize: validateProxyBodySize(config.experimental.proxyClientMaxBodySize) };
+  const lazyDynamicImports=config.experimental.lazyDynamicImports===undefined?false:config.experimental.lazyDynamicImports;
+  if(typeof lazyDynamicImports!=='boolean')throw new Error(`${filename}: experimental.lazyDynamicImports must be a boolean.`);
+  const streamingRequestBodies = config.experimental.streamingRequestBodies === undefined ? false : config.experimental.streamingRequestBodies;
+  const nativePprShell = config.experimental.nativePprShell === undefined ? false : config.experimental.nativePprShell;
+  for (const [key, value] of Object.entries({streamingRequestBodies, nativePprShell})) {
+    if (typeof value !== 'boolean') throw new Error(`${filename}: experimental.${key} must be a boolean.`);
+  }
+  if (nativePprShell && !config.cacheComponents) throw new Error(`${filename}: experimental.nativePprShell requires cacheComponents: true.`);
+  let parallelBuilds = config.experimental.parallelBuilds === undefined ? false : config.experimental.parallelBuilds;
+  if (parallelBuilds !== false) {
+    if (parallelBuilds === true) parallelBuilds = {};
+    if (!parallelBuilds || typeof parallelBuilds !== 'object' || Array.isArray(parallelBuilds)) throw new Error(`${filename}: experimental.parallelBuilds must be a boolean or an object.`);
+    for (const key of Object.keys(parallelBuilds)) if (!['maxWorkers', 'maxMemoryMb'].includes(key)) throw new Error(`${filename}: unknown parallelBuilds option ${key}.`);
+    parallelBuilds = {maxWorkers: parallelBuilds.maxWorkers === undefined ? 4 : parallelBuilds.maxWorkers, maxMemoryMb: parallelBuilds.maxMemoryMb === undefined ? 1024 : parallelBuilds.maxMemoryMb};
+    if (!Number.isInteger(parallelBuilds.maxWorkers) || parallelBuilds.maxWorkers < 1 || parallelBuilds.maxWorkers > 8) throw new Error(`${filename}: parallelBuilds.maxWorkers must be between 1 and 8.`);
+    if (!Number.isInteger(parallelBuilds.maxMemoryMb) || parallelBuilds.maxMemoryMb < 256 || parallelBuilds.maxMemoryMb > 8192) throw new Error(`${filename}: parallelBuilds.maxMemoryMb must be between 256 and 8192.`);
+  }
+  config.experimental = { nextScriptWorkers, lazyDynamicImports, streamingRequestBodies, nativePprShell, parallelBuilds, serverActions: validateServerActions(config.experimental.serverActions), optimizePackageImports: validateOptimizePackageImports(config.experimental.optimizePackageImports), proxyClientMaxBodySize: validateProxyBodySize(config.experimental.proxyClientMaxBodySize) };
   for (const key of ['basePath', 'assetPrefix']) {
     if (typeof config[key] !== 'string' || Buffer.byteLength(config[key]) > 4096) throw new Error(`${filename}: ${key} must be a string of at most 4096 bytes.`);
   }

package/build/create.mjs

@@ -129,7 +129,7 @@ h1 { font-size: clamp(2.5rem, 8vw, 4rem); letter-spacing: -.04em; }
 p { line-height: 1.6; }
 code { font-size: .95em; }
 `],
-    ['.gitignore', 'node_modules/\n.prnext/\n.prnext-types/\n.prnext-dev/\n.prnext-cache/\n.env*\n!.env.example\n*.tsbuildinfo\n'],
+    ['.gitignore', 'node_modules/\n.prnext/\n.prnext-types/\n.prnext-dev/\n.prnext-cache/\n.prnext-gc/\n.env*\n!.env.example\n*.tsbuildinfo\n'],
     ['README.md', `# ${name}\n\nA minimal PRNext application.\n\nRun \`npm install\` if dependencies have not been installed, then:\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nEdit \`app/page.${extension}\`. Use the local URL printed by the server.\n\n\`\`\`sh\nnpm run check\n${typescript ? 'npm run typecheck\n' : ''}npm run build\nnpm start\n\`\`\`\n\nUse another port with \`npm run dev -- --port 3001\` when needed.\n\n[PRNext documentation](https://prnext.dev) · Installed AI guide: \`npx --no-install prnext docs --ai\`.\nPRNext is experimental; Next.js compatibility is partial.\n`],
     ['AGENTS.md', `# PRNext project\n\nThis application uses \`@thomas.f/prnext\`. Before changing routing, configuration, data fetching or deployment, read the installed guide at \`node_modules/@thomas.f/prnext/AI.md\` or run:\n\n\`\`\`sh\nnpx --no-install prnext docs --ai\nnpx --no-install prnext docs --ai --list\n\`\`\`\n\nRead only the relevant topic with \`npx --no-install prnext docs --ai <topic>\`. The installed documentation is version-specific; do not assume full Next.js compatibility. Preserve the project's package manager and lockfile.\n`],
   ]);

package/build/css-modules.mjs

@@ -138,6 +138,10 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
 
   return {
     compile:get,
+    async parallelSafe() {
+      eligibility ??= cacheEligible();
+      return typeof sassOptions?.additionalData !== 'function' && await eligibility;
+    },
     async mappings(){return Promise.all([...cache].map(async([file,result])=>({file,mapping:(await result).mapping,watchFiles:(await result).watchFiles})));},
     plugin(browser, { emitStyles = () => true } = {}) {
       return {

package/build/dev-action-graph.mjs

@@ -0,0 +1,21 @@
+import path from 'node:path';
+
+// Build-private provenance, never Action arguments, source text or encryption
+// material. Unknown/external owners deliberately disable selective refresh.
+export function developmentActionMetadata(root, actions) {
+  const records = [], identities = new Set(); let bytes = 0;
+  for (const action of actions) {
+    const file = path.relative(root, action.file).replaceAll(path.sep, '/');
+    const runtimes = [...(action.runtimes?.size ? action.runtimes : ['nodejs'])].sort();
+    const record = { id: action.id, file, binding: action.binding, runtimes };
+    const identity = file + '\0' + action.binding;
+    if (!/^[a-f0-9]{64}$/.test(action.id) || !file || file.startsWith('../') || path.isAbsolute(file) || /[:?\0]/.test(file) || file.startsWith('node_modules/') ||
+        typeof action.binding !== 'string' || !action.binding || action.binding.length > 1024 || identities.has(identity) ||
+        runtimes.some(runtime => !['nodejs', 'edge'].includes(runtime)) || records.length >= 10000 ||
+        (bytes += Buffer.byteLength(JSON.stringify(record))) > 1024 * 1024)
+      return { version: 1, complete: false, actions: [] };
+    identities.add(identity); records.push(record);
+  }
+  records.sort((a, b) => a.file.localeCompare(b.file) || a.binding.localeCompare(b.binding));
+  return { version: 1, complete: true, actions: records };
+}

package/build/dev-css-assets.mjs

@@ -0,0 +1,173 @@
+import { copyFile, link, lstat, mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { rename } from '../runtime/fs.mjs';
+
+export const STYLE_OVERLAY_LIMITS = Object.freeze({ files: 4096, bytes: 64 * 1024 * 1024, catalogueBytes: 4 * 1024 * 1024, references: 16384 });
+const digest = data => createHash('sha256').update(data).digest('hex');
+const filename = name => typeof name === 'string' && name.length > 0 && name.length <= 255 && name !== '.' && name !== '..'
+  && !/[\\/\x00-\x1f<>:"|?*#]/.test(name) && path.basename(name) === name;
+const inside = (root, file) => { const relative = path.relative(root, file); return relative !== '' && !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep); };
+
+export class StyleOverlayFallback extends Error {
+  constructor(code) { super(code); this.code = code; }
+}
+const fallback = code => { throw new StyleOverlayFallback(code); };
+
+function assetsFor(bundles) {
+  const assets = new Map();
+  let references = 0, bytes = 0;
+  for (const files of bundles.values()) for (const file of files) {
+    if (++references > STYLE_OVERLAY_LIMITS.references) fallback('style-overlay-budget');
+    if (!file || !filename(file.name) || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > STYLE_OVERLAY_LIMITS.bytes || !/^[a-f0-9]{64}$/.test(file.sha256)) fallback('invalid-style-overlay');
+    const previous = assets.get(file.name);
+    if (previous && (previous.bytes !== file.bytes || previous.sha256 !== file.sha256)) fallback('conflicting-style-overlay');
+    if (!previous) {
+      assets.set(file.name, file);
+      bytes += file.bytes;
+      if (assets.size > STYLE_OVERLAY_LIMITS.files || bytes > STYLE_OVERLAY_LIMITS.bytes) fallback('style-overlay-budget');
+    }
+  }
+  return assets;
+}
+
+function catalogue(previous, plans) {
+  const bundles = new Map();
+  if (!previous) return bundles;
+  if (previous.version !== 1 || typeof previous.baseDirectory !== 'string' || previous.baseDirectory.length > 4096
+    || !Array.isArray(previous.bundles) || previous.bundles.length > STYLE_OVERLAY_LIMITS.files) fallback('invalid-style-overlay');
+  let references = 0;
+  for (const entry of previous.bundles) {
+    if (!Array.isArray(entry) || entry.length !== 2 || !plans.has(entry[0]) || bundles.has(entry[0]) || !Array.isArray(entry[1]) || entry[1].length > STYLE_OVERLAY_LIMITS.files) fallback('invalid-style-overlay');
+    references += entry[1].length;
+    if (references > STYLE_OVERLAY_LIMITS.references) fallback('style-overlay-budget');
+    if (!entry[1].some(file => file?.name === entry[0])) fallback('invalid-style-overlay');
+    bundles.set(entry[0], entry[1]);
+  }
+  assetsFor(bundles);
+  if (Buffer.byteLength(JSON.stringify(previous)) > STYLE_OVERLAY_LIMITS.catalogueBytes) fallback('style-overlay-budget');
+  return bundles;
+}
+
+async function inspect(file) {
+  const info = await lstat(file);
+  if (!info.isFile() || info.size > STYLE_OVERLAY_LIMITS.bytes) fallback('invalid-style-overlay');
+  const data = await readFile(file);
+  return { name: path.basename(file), bytes: data.byteLength, sha256: digest(data) };
+}
+
+/** A CSS generation owns only explicitly catalogued stylesheet assets. */
+export async function createStyleOverlay({ root, source, destination, baseSource = source, manifest, plans, selected }) {
+  const previous = manifest.devStyles.overlay;
+  if (!previous && manifest.devStyles.baseClient) fallback('missing-style-overlay');
+  if (previous && !manifest.devStyles.baseClient) fallback('invalid-style-overlay');
+  if (!Array.isArray(plans) || plans.length > STYLE_OVERLAY_LIMITS.files) fallback('style-overlay-budget');
+  const names = new Set(plans.map(([name]) => name));
+  if (names.size !== plans.length || ![...names].every(filename)) fallback('invalid-style-overlay');
+  const bundles = catalogue(previous, names), previousAssets = assetsFor(bundles);
+  const selectedNames = new Set(selected.map(([name]) => name));
+  if ([...selectedNames].some(name => !names.has(name))) fallback('invalid-style-overlay');
+  for (const route of manifest.routes || []) for (const url of route.css || []) {
+    if (url.includes('?v=') && !bundles.has(path.posix.basename(url.split('?')[0]))) fallback('missing-style-overlay');
+  }
+  const [canonicalRoot, canonicalSource, canonicalBase, parent, sourceAssets] = await Promise.all([realpath(root), realpath(source), realpath(baseSource), realpath(path.dirname(destination)), realpath(path.join(source, 'assets'))]).catch(error => {
+    if (error.code === 'ENOENT') fallback('missing-style-overlay');
+    throw error;
+  });
+  // The destination does not exist yet. Its existing parent supplies the real
+  // identity, including macOS /var aliases and Windows short-name prefixes.
+  const canonicalDestination = path.join(parent, path.basename(destination));
+  if (!inside(canonicalRoot, canonicalSource) || !inside(canonicalRoot, canonicalBase)
+    || parent !== canonicalRoot && !inside(canonicalRoot, parent) || !inside(canonicalRoot, canonicalDestination)
+    || canonicalDestination === canonicalSource || canonicalDestination === canonicalBase
+    || inside(canonicalDestination, canonicalSource) || inside(canonicalSource, canonicalDestination)
+    || inside(canonicalDestination, canonicalBase) || inside(canonicalBase, canonicalDestination)
+    || sourceAssets !== path.join(canonicalSource, 'assets')) fallback('invalid-style-overlay-directory');
+  const baseDirectory = path.relative(canonicalRoot, canonicalBase).replaceAll(path.sep, '/');
+  if (previous ? previous.baseDirectory !== baseDirectory : canonicalSource !== canonicalBase) fallback('invalid-style-overlay-base');
+  const assetsDirectory = path.join(destination, 'assets');
+  let owned = false;
+  async function inherit(file) {
+    const from = path.join(source, 'assets', file.name), target = path.join(assetsDirectory, file.name);
+    let actual;
+    try { actual = await inspect(from); } catch (error) { if (error.code === 'ENOENT') fallback('missing-style-overlay-asset'); throw error; }
+    if (actual.bytes !== file.bytes || actual.sha256 !== file.sha256) fallback('invalid-style-overlay-asset');
+    try { await link(from, target); }
+    catch (error) {
+      if (!['EXDEV', 'EPERM', 'ENOTSUP', 'EACCES'].includes(error.code)) throw error;
+      await copyFile(from, target);
+    }
+  }
+  try {
+    await mkdir(destination);
+    owned = true;
+    await mkdir(assetsDirectory);
+    for (const name of selected.map(([name]) => name)) bundles.delete(name);
+    for (const file of assetsFor(bundles).values()) await inherit(file);
+  } catch (error) {
+    if (owned) await rm(destination, { recursive: true, force: true });
+    throw error;
+  }
+
+  return {
+    async recordBundle(name, result) {
+      if (!selectedNames.has(name)) fallback('invalid-style-overlay-output');
+      const files = new Map();
+      for (const output of result.outputFiles) {
+        if (path.dirname(path.resolve(output.path)) !== path.resolve(assetsDirectory) || !filename(path.basename(output.path))) fallback('invalid-style-overlay-output');
+        const file = { name: path.basename(output.path), bytes: output.contents.byteLength, sha256: digest(output.contents) };
+        files.set(file.name, file);
+      }
+      if (!files.has(name)) fallback('invalid-style-overlay-output');
+      // CSS Module compilation emits its URL assets before the outer CSS
+      // bundle. Its absolute, external URL-token imports identify exactly the
+      // emitted images/fonts to retain, without scanning the JavaScript build.
+      const prefix = manifest.config.assetBase.replace(/\/$/, '') + '/';
+      for (const output of Object.values(result.metafile.outputs)) for (const item of output.imports || []) {
+        if (item.kind !== 'url-token' || !item.external || !item.path.startsWith(prefix)) continue;
+        let name;
+        try { name = decodeURIComponent(item.path.slice(prefix.length).split(/[?#]/)[0]); }
+        catch { fallback('invalid-style-overlay-output'); }
+        if (!filename(name) || files.has(name)) continue;
+        let file;
+        try { file = await inspect(path.join(assetsDirectory, name)); }
+        catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+          const previous = previousAssets.get(name);
+          if (!previous) continue; // An unchanged base or public asset stays in its original generation.
+          await inherit(previous);
+          file = previous;
+        }
+        files.set(name, file);
+      }
+      bundles.set(name, [...files.values()]);
+      assetsFor(bundles); // Validate the aggregate budget before publishing bytes.
+      for (const output of result.outputFiles) {
+        const file = files.get(path.basename(output.path));
+        let existing;
+        try { existing = await inspect(output.path); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+        if (existing) {
+          if (existing.bytes !== file.bytes || existing.sha256 !== file.sha256) fallback('conflicting-style-overlay');
+          continue;
+        }
+        const temporary = output.path + '.' + randomUUID() + '.tmp';
+        try { await writeFile(temporary, output.contents); await rename(temporary, output.path); }
+        finally { await rm(temporary, { force: true }); }
+      }
+    },
+    async finish() {
+      const assets = assetsFor(bundles);
+      const value = { version: 1, baseDirectory, bundles: [...bundles] };
+      if (Buffer.byteLength(JSON.stringify(value)) > STYLE_OVERLAY_LIMITS.catalogueBytes) fallback('style-overlay-budget');
+      // This directory was created above for CSS only. Remove module assets
+      // that no current bundle references, rather than accumulating old URLs.
+      const entries = await readdir(assetsDirectory, { withFileTypes: true });
+      if (entries.length > STYLE_OVERLAY_LIMITS.references) fallback('style-overlay-budget');
+      for (const entry of entries) {
+        if (!entry.isFile() || !filename(entry.name)) fallback('invalid-style-overlay-output');
+        if (!assets.has(entry.name)) await rm(path.join(assetsDirectory, entry.name));
+      }
+      return value;
+    },
+  };
+}

package/build/dev-css-update.mjs

@@ -1,14 +1,15 @@
 import {build as bundle} from 'esbuild';
-import {readFile,writeFile,rm,stat,readdir} from 'node:fs/promises';
+import {readFile,writeFile,rm,stat} from 'node:fs/promises';
 import path from 'node:path';
 import {randomUUID} from 'node:crypto';
 import {rename} from '../runtime/fs.mjs';
 import {createCssModules} from './css-modules.mjs';
 import {recordDevDependencies,developmentStyleDependencies} from './dev-dependencies.mjs';
 import {writeBuildOutput} from './output-contract.mjs';
+import {createStyleOverlay,StyleOverlayFallback} from './dev-css-assets.mjs';
 
 /** Publish only styles when all JS-visible class maps remain identical. */
-export async function tryDevCssUpdate({root,source,destination,manifest,changed,sequence,cssEngine,snapshot,onFallback=()=>{}}){
+export async function tryDevCssUpdate({root,source,baseSource=source,destination,manifest,changed,sequence,cssEngine,onFallback=()=>{}}){
   const fallback=code=>{onFallback(code);return undefined;};
   if(!changed.length||changed.some(file=>!file.endsWith('.css'))||!manifest.devStyles?.bundles.length||manifest.app?.globalError?.css?.length)return;
   if(!manifest.config.assetBase.startsWith('/'))return fallback('external-asset-base');
@@ -32,8 +33,9 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
   if(changed.some(file=>!known.has(path.join(root,file))))return fallback('unknown-style-dependency');
   if(!selected.length)return fallback('unknown-style-dependency');
   const stage=destination,modules=createCssModules({projectRoot:root,stage,assetBase:manifest.config.assetBase,cssEngine,dev:true});
+  let overlay;
   try{
-    await snapshot(source,stage);
+    overlay=await createStyleOverlay({root,source,baseSource,destination,manifest,plans,selected});
     for(const previous of manifest.devStyles.modules.filter(module=>(module.watchFiles||[module.file]).some(file=>changedPaths.has(file)))){
       if(!previous.file.endsWith('.css')){await rm(stage,{recursive:true,force:true});return fallback('stylesheet-language');}
       if((await modules.compile(previous.file)).mapping!==previous.mapping){await rm(stage,{recursive:true,force:true});return fallback('css-module-exports');}
@@ -42,7 +44,7 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
     for(const [name,files]of selected){
       const options={absWorkingDir:root,stdin:{contents:files.map(file=>`@import ${JSON.stringify(file.replace(/^prnext-compiled-css:/,'prnext-css:'))};`).join('\n'),resolveDir:root,loader:'css'},outfile:path.join(stage,'assets',name),bundle:true,write:false,metafile:true,logLevel:'silent',publicPath:manifest.config.assetBase,assetNames:'[name]-[hash]',loader:Object.fromEntries(['.png','.jpg','.jpeg','.svg','.gif','.webp','.avif','.woff','.woff2','.ttf'].map(ext=>[ext,'file'])),plugins:[modules.plugin(true)]};
       const result=await bundle(options);recordDevDependencies(state,options,result);
-      for(const output of result.outputFiles){const temporary=output.path+'.'+randomUUID()+'.tmp';try{await writeFile(temporary,output.contents);await rename(temporary,output.path);}finally{await rm(temporary,{force:true});}}
+      await overlay.recordBundle(name,result);
     }
     const compiled=await modules.mappings();
     if(compiled.some(value=>!manifest.devStyles.modules.some(previous=>previous.file===value.file&&previous.mapping===value.mapping))){await rm(stage,{recursive:true,force:true});return fallback('css-module-exports');}
@@ -51,7 +53,8 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
       for(const module of updated)if(files.includes(module.file))for(const file of module.watchFiles)if(!files.includes(file))files.push(file);
       dependencies.set(name,files);
     }
-    const buildId=randomUUID(),baseClient=manifest.devStyles.baseClient||manifest.devClient,next={...manifest,buildId,devSequence:sequence,devClient:manifest.config.assetBase+'/dev-manifest-'+buildId+'.json',outputDirectory:stage,devStyles:{baseClient,bundles:plans,dependencies:[...dependencies],modules:updated}};
+    const assets=await overlay.finish();
+    const buildId=randomUUID(),baseClient=manifest.devStyles.baseClient||manifest.devClient,next={...manifest,buildId,devSequence:sequence,devClient:manifest.config.assetBase+'/dev-manifest-'+buildId+'.json',outputDirectory:stage,devStyles:{baseClient,overlay:assets,bundles:plans,dependencies:[...dependencies],modules:updated}};
     // Keep route invalidation conservative as CSS imports are added or removed.
     // Unchanged routes retain their original dependency arrays.
     next.devDependencies=(manifest.devDependencies||[]).map(route=>{
@@ -66,7 +69,10 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
       }
       return {...route,files:[...files]};
     });
-    const old=JSON.parse(await readFile(path.join(source,'assets',path.basename(manifest.devClient)),'utf8'));
+    let old;
+    try{old=JSON.parse(await readFile(path.join(source,'assets',path.basename(manifest.devClient)),'utf8'));}
+    catch(error){if(error.code==='ENOENT'||error instanceof SyntaxError)throw new StyleOverlayFallback('missing-style-manifest');throw error;}
+    if(!Array.isArray(old?.pages)||old.pages.some(page=>!Array.isArray(page.css))||old.app&&(!Array.isArray(old.app.css)||!Array.isArray(old.app.routes)||old.app.routes.some(route=>!Array.isArray(route.css))))throw new StyleOverlayFallback('invalid-style-manifest');
     old.buildId=buildId;
     const changedNames=new Set(selected.map(([name])=>name));
     const revise=urls=>urls.map(url=>changedNames.has(path.posix.basename(url.split('?')[0]))?url.split('?')[0]+'?v='+buildId:url);
@@ -74,12 +80,8 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
     for(const page of old.pages)page.css=revise(page.css);if(old.app){old.app.css=revise(old.app.css);for(const route of old.app.routes||[]){route.css=revise(route.css);if(route.cssScopes)route.cssScopes=reviseScopes(route.cssScopes);}}
     next.routes=next.routes.map(route=>({...route,css:revise(route.css||[]),...(route.cssScopes?{cssScopes:reviseScopes(route.cssScopes)}:{})}));
     await writeFile(path.join(stage,'assets',path.basename(next.devClient)),JSON.stringify(old));
-    const protectedNames=new Set([path.basename(baseClient),path.basename(next.devClient)]),history=[];
-    for(const name of await readdir(path.join(stage,'assets')))if(/^dev-manifest-.*\.json$/.test(name)&&!protectedNames.has(name)){const info=await stat(path.join(stage,'assets',name));history.push({name,size:info.size,time:info.mtimeMs});}
-    history.sort((a,b)=>b.time-a.time);let bytes=0;
-    for(let i=0;i<history.length;i++){bytes+=history[i].size;if(i>=32||bytes>4*1024*1024)await rm(path.join(stage,'assets',history[i].name));}
     const temporary=path.join(stage,'manifest.'+buildId+'.tmp');await writeFile(temporary,JSON.stringify(next));await rename(temporary,path.join(stage,'manifest.json'));
-    await rm(path.join(stage,'build-output.json'));await writeBuildOutput(stage,next);
+    await writeBuildOutput(stage,next);
     return next;
-  }catch(error){await rm(stage,{recursive:true,force:true});throw error;}
+  }catch(error){if(overlay)await rm(stage,{recursive:true,force:true});if(error instanceof StyleOverlayFallback)return fallback(error.code);throw error;}
 }

package/build/dev-lazy-build.mjs

@@ -0,0 +1,77 @@
+import { mkdir, readdir, lstat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { compileApp } from './app.mjs';
+import { configureCompiler } from './compiler.mjs';
+import { createCssModules } from './css-modules.mjs';
+import { createFonts } from './fonts.mjs';
+import { createImages } from './images.mjs';
+import { discardLazyBuild } from '../runtime/dev-lazy-staging.mjs';
+import { loadEnvConfig } from '../runtime/env.mjs';
+
+// Only the latest successful ordinary generation per project is reusable.
+// This private compiler-process registry is not part of browser metadata or IPC.
+const contexts = new Map();
+const CONTEXT_LIMIT = 8, FILE_LIMIT = 16384, BYTE_LIMIT = 128 * 1024 * 1024;
+export function forgetLazyBuildContext(root) {
+  if (root === undefined) contexts.clear(); else contexts.delete(root);
+}
+export function rememberLazyBuildContext(root, { manifest, config, environment, tsconfig, envMode }) {
+  contexts.delete(root);
+  if (!manifest.devLazy || !manifest.dev || !config.experimental.lazyDynamicImports) return;
+  while (contexts.size >= CONTEXT_LIMIT) contexts.delete(contexts.keys().next().value);
+  contexts.set(root, { config, environment, tsconfig, envMode, cacheId: manifest.cacheId,
+    buildId: manifest.buildId, session: manifest.devSession,
+    manifestConfig: structuredClone(manifest.config) });
+}
+/** Reuse the validated configuration of the running generation, not its routes. */
+export async function tryBuildLazyGraph(root, { base, request, devInputs, devSession,
+  devActionSecret, incremental = true } = {}) {
+  if (!base || typeof base.cacheId !== 'string' || !request) throw Error('Invalid deferred build generation');
+  const context = contexts.get(root);
+  // Compiler recycling loses its private context. The caller retains the ordinary
+  // build path for this recovery case; it must never guess another generation.
+  if (!context || context.cacheId !== base.cacheId || context.session !== devSession) return;
+  // Preserve the running generation's env-file mode for supported build-time
+  // hooks. The enclosing build() scope restores the caller's env on every exit.
+  loadEnvConfig(root,{dev:true,mode:context.envMode,inputs:devInputs});
+  const { config, environment, tsconfig } = context;
+  const stage = path.join(root, '.prnext-build-' + randomUUID());
+  try {
+    await mkdir(path.join(stage, '.entries'), { recursive: true });
+    const manifest = { version: 1, dev: true, buildId: context.buildId,
+      cacheId: context.cacheId, devSession, config: structuredClone(context.manifestConfig),
+      routes: [], prerendered: [] };
+    const project = { root, routes: [] };
+    configureCompiler({ config, root, stage, buildId: context.buildId, dev: true,
+      incremental, devInputs, tsconfig, assetBase: manifest.config.assetBase });
+    const fonts = createFonts({ projectRoot: root, stage, assetBase: manifest.config.assetBase });
+    const cssModules = createCssModules({ projectRoot: root, stage,
+      assetBase: manifest.config.assetBase, sassOptions: config.sassOptions,
+      cssEngine: config.cssEngine, dev: true, config });
+    const images = await createImages({ projectRoot: root, stage,
+      assetBase: manifest.config.assetBase, config: config.images });
+    await compileApp({ project, stage, manifest, cssModules, fonts, images, dev: true,
+      devActionSecret, reactCompiler: config.reactCompiler, defineEnvironment: environment,
+      moduleResolution: config.turbopack, serverExternalPackages: config.serverExternalPackages,
+      lazyDynamicImports: true, devLazyRequest: request, devLazyOnly: true });
+    const files = [];
+    let bytes = 0;
+    // This unpublished stage contains only this deferred graph, never other
+    // routes or a copied framework runtime. Publication uses this exact receipt.
+    for (const entry of await readdir(path.join(stage, 'assets'), { withFileTypes: true })) {
+      if (!entry.isFile() || files.length >= FILE_LIMIT) throw Error('Invalid or excessive deferred output assets');
+      const info = await lstat(path.join(stage, 'assets', entry.name));
+      bytes += info.size;
+      if (!info.isFile() || bytes > BYTE_LIMIT) throw Error('Deferred output exceeds the 128 MiB generation budget');
+      files.push({ name: entry.name, bytes: info.size });
+    }
+    files.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    return { ...manifest, outputDirectory: stage, devLazyTemporary: true,
+      devLazyAssets: { version: 1, baseCacheId: context.cacheId, files } };
+  } catch (error) {
+    try { await discardLazyBuild(root, { outputDirectory: stage, devLazyTemporary: true }); }
+    catch (cleanupError) { error.cleanupError = cleanupError; error.message += '; deferred compiler staging cleanup also failed'; }
+    throw error;
+  }
+}

package/build/dynamic.mjs

@@ -59,17 +59,19 @@ function loaderBody(loader) {
 }
 
 /** Add shared hydration IDs without resolving, evaluating or eagerly importing loaders. */
-export function transformDynamicImports(source, filename, { projectRoot, mode = 'browser' } = {}) {
+export function transformDynamicImports(source, filename, { projectRoot, mode = 'browser',dev=false } = {}) {
   if (![...sources].some(name => source.includes(name))) return source;
   projectRoot ||= process.cwd();
-  return cachedTransform('dynamic',source,[filename,projectRoot,mode],()=>transformDynamicImportsUncached(source,filename,{projectRoot,mode}));
+  return cachedTransform('dynamic',source,[filename,projectRoot,mode,dev],()=>transformDynamicImportsUncached(source,filename,{projectRoot,mode,dev}));
 }
 
-function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
+function transformDynamicImportsUncached(source, filename, {projectRoot,mode,dev}) {
   const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: filename,
     plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] });
   const relative = path.relative(projectRoot || process.cwd(), filename).replaceAll(path.sep, '/');
+  const developmentRevision=dev&&mode==='browser'?createHash('sha256').update(generate(ast,{compact:true,comments:false}).code).digest('hex'):undefined;
   let changed = false;
+  let ordinal=0;
   traverse(ast, {
     CallExpression(call) {
       let callee = call.get('callee');
@@ -105,6 +107,10 @@ function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
       const generated = t.objectProperty(t.identifier('loadableGenerated'), t.objectExpression([
         t.objectProperty(t.identifier('modules'), t.arrayExpression(ids.map(id => t.stringLiteral(id)))),
       ]));
+      const statement=call.findParent(value=>value.isStatement());
+      const declaration=statement?.parentPath?.isExportNamedDeclaration()?statement.parentPath:statement;
+      const stableModuleCall=call.scope===call.scope.getProgramParent()&&declaration?.parentPath?.isProgram()&&!t.isLoop(declaration.node);
+      const identity=developmentRevision&&stableModuleCall?t.objectProperty(t.identifier('__prnextDevIdentity'),t.stringLiteral(createHash('sha256').update(relative+'\0'+ordinal+++'\0'+developmentRevision).digest('hex').slice(0,24))):undefined;
 
       if (noSSR && mode !== 'browser') {
         const empty = t.arrowFunctionExpression([], t.nullLiteral(), true);
@@ -115,9 +121,10 @@ function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
         loader.replaceWith(t.arrowFunctionExpression([], loader.node));
       }
       const target = secondOptions || firstOptions;
-      if (target?.isObjectExpression()) target.node.properties.push(generated);
-      else if (target?.node) target.replaceWith(t.objectExpression([t.spreadElement(target.node), generated]));
-      else call.node.arguments.push(t.objectExpression([generated]));
+      const fields=[generated,...(identity?[identity]:[])];
+      if (target?.isObjectExpression()) target.node.properties.push(...fields);
+      else if (target?.node) target.replaceWith(t.objectExpression([t.spreadElement(target.node), ...fields]));
+      else call.node.arguments.push(t.objectExpression(fields));
       changed = true;
     },
   });

package/build/font-cache.mjs

@@ -1,5 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, readFile, writeFile, rename, rm, readdir, lstat } from 'node:fs/promises';
+import { open, writeFile, rename, rm, readdir, lstat } from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {privateCacheDirectory} from './persistent-cache.mjs';
 import path from 'node:path';
 
 const hash = value => createHash('sha256').update(value).digest('hex');
@@ -11,12 +13,14 @@ let writes = Promise.resolve();
  */
 export async function cachedFontResource(root, url, maximum, accept, download) {
   if (!root) return download();
-  const directory = path.join(root, '.prnext-cache', 'fonts-v1');
+  const directory = await privateCacheDirectory(root,'fonts-v1');
+  if(!directory)return download();
   const file = path.join(directory, hash(JSON.stringify([url, accept])) + '.bin');
   try {
     const metadata = await lstat(file);
-    if (metadata.isFile() && metadata.size > 65 && metadata.size <= maximum + 65) {
-      const stored = await readFile(file);
+    if (metadata.isFile() && !metadata.isSymbolicLink() && metadata.size > 65 && metadata.size <= maximum + 65) {
+      const handle=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW||0));
+      let stored;try{const info=await handle.stat();if(!info.isFile()||info.size>maximum+65)throw Object.assign(Error('Font cache changed'),{code:'ENOENT'});stored=await handle.readFile();}finally{await handle.close();}
       const bytes = stored.subarray(65);
       if (stored[64] === 10 && hash(bytes) === stored.toString('ascii', 0, 64)) return bytes;
     }
@@ -24,10 +28,9 @@ export async function cachedFontResource(root, url, maximum, accept, download) {
   const bytes = await download();
   if (!bytes.length || bytes.length > maximum) throw new Error('Font resource exceeds its cache input limit');
   const task = writes.catch(() => {}).then(async () => {
-    await mkdir(directory, { recursive: true });
     const temporary = file + '.' + randomUUID() + '.tmp';
     try {
-      await writeFile(temporary, Buffer.concat([Buffer.from(hash(bytes) + '\n'), bytes]), { flag: 'wx' });
+      await writeFile(temporary, Buffer.concat([Buffer.from(hash(bytes) + '\n'), bytes]), { flag: 'wx',mode:0o600 });
       await rename(temporary, file);
     } finally { await rm(temporary, { force: true }); }
     const entries = [];

package/build/font-files.mjs

@@ -183,7 +183,7 @@ async function google(name, options, context) {
 }
 
 async function fallbackMetrics(faces, fallbackName) {
-  const { create } = await import('fontkit');
+  const { create } = await import('../vendor/fontkit/index.mjs');
   // Prefer an upright face near the normal text weight for a shared fallback.
   const candidates = [...faces].sort((a, b) => Number(a.style === 'italic') - Number(b.style === 'italic') || Math.abs((parseFloat(a.weight) || 400) - 400) - Math.abs((parseFloat(b.weight) || 400) - 400));
   for (const face of candidates) {