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

package/runtime/dev-file-changes.mjs

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {createReadStream} from 'node:fs';
-import {stat, readdir} from 'node:fs/promises';
+import {stat, lstat, readdir, opendir} from 'node:fs/promises';
 import {shouldWatchProjectFile} from './env.mjs';
 
 function directoryFingerprint(entries) {
@@ -12,16 +12,27 @@ function directoryFingerprint(entries) {
 
 // Remember the bytes actually consumed by webpack, not the file's contents at
 // the end of a build: an edit made after a read must still trigger a rebuild.
-export function createDevInputSnapshot(roots, {maxEntries=512,maxBytes=1024*1024}={}) {
+export function createDevInputSnapshot(roots, {maxEntries=process.platform==='darwin'?8192:512,maxBytes=1024*1024}={}) {
   const inputs=new Map();
+  const limitedPrefixes=new Set();let globalLimited=false;
   let bytes=0;
+  function limited(relative) {
+    // Source files may overflow in many sibling folders. One source-root
+    // prefix remains bounded without invalidating a captured disjoint generator.
+    relative=relative==='.contentlayer/generated'||relative.startsWith('.contentlayer/generated/')?'.contentlayer/generated':relative.split('/')[0];
+    if(globalLimited)return;
+    if([...limitedPrefixes].some(prefix=>relative===prefix||relative.startsWith(prefix+'/')))return;
+    for(const prefix of limitedPrefixes)if(prefix.startsWith(relative+'/'))limitedPrefixes.delete(prefix);
+    limitedPrefixes.add(relative);
+    if(limitedPrefixes.size>32||[...limitedPrefixes].reduce((sum,value)=>sum+value.length*2,0)>4096){globalLimited=true;limitedPrefixes.clear();}
+  }
   function remember(relative,value) {
     if (inputs.has(relative)) {
       if (inputs.get(relative)!==value) inputs.set(relative,null);
       return;
     }
     const size=relative.length*2+value.length*2+64;
-    if (inputs.size>=maxEntries || bytes+size>maxBytes) return;
+    if (inputs.size>=maxEntries || bytes+size>maxBytes) {limited(value.startsWith('directory:')?relative:path.posix.dirname(relative)==='.'?relative:path.posix.dirname(relative));return;}
     inputs.set(relative,value);bytes+=size;
   }
   return {
@@ -38,14 +49,15 @@ export function createDevInputSnapshot(roots, {maxEntries=512,maxBytes=1024*1024
     async captureDirectory(relative) {
       // Called after an awaited content generator and before graph resolution.
       // Include its types/aggregate indexes, which may not be runtime imports.
-      if (!shouldWatchProjectFile(relative) || inputs.size>=maxEntries || bytes>=maxBytes) return;
+      if (!shouldWatchProjectFile(relative))return;
+      if(inputs.size>=maxEntries || bytes>=maxBytes){limited(relative);return;}
       const file=path.join(roots[0],relative);
       let entries;
       try {entries=await readdir(file,{withFileTypes:true});}
       catch(error){if(error.code==='ENOENT')return;throw error;}
       remember(relative,directoryFingerprint(entries));
       for(const entry of entries) {
-        if(inputs.size>=maxEntries || bytes>=maxBytes)break;
+        if(inputs.size>=maxEntries || bytes>=maxBytes){limited(relative);break;}
         const child=relative+'/'+entry.name;
         if(!shouldWatchProjectFile(child))continue;
         if(entry.isDirectory())await this.captureDirectory(child);
@@ -58,14 +70,90 @@ export function createDevInputSnapshot(roots, {maxEntries=512,maxBytes=1024*1024
         }
       }
     },
-    entries:()=>[...inputs],
+    entries:()=>{
+      const values=[...inputs],coverage={version:1,limitedPrefixes:[...limitedPrefixes],globalLimited};
+      if(values.length)values[0]=[...values[0],coverage];
+      else values.push([null,null,coverage]);
+      return values;
+    },
   };
 }
 
 // Generators may rewrite identical JSON/modules on every compilation. Retain
 // only bounded path/digest pairs, never file contents or full directory lists.
-export function createDevChangeFilter(root, {maxEntries=512,maxBytes=1024*1024}={}) {
+export function createDevChangeFilter(root, {directoryEventsAreRecursive=false,maxEntries=directoryEventsAreRecursive?8192:512,maxBytes=1024*1024,ignore=()=>false,maxTreeEntries=8192,maxTreeBytes=1024*1024,onUncertainDirectory=()=>{}}={}) {
   const fingerprints=new Map();
+  // Before the first build there are no consumed inputs to lose. A later
+  // acceptInputs without coverage metadata deliberately replaces this proof.
+  const trees=new Map(),diagnostics=new Map();let treeBytes=0,coverage={version:1,limitedPrefixes:[],globalLimited:false},consumedInputs=new Map();
+  const contains=(parent,file)=>file===parent||file.startsWith(parent+'/');
+  const allowed=file=>shouldWatchProjectFile(file)&&!ignore(file);
+  const limitedFor=file=>!coverage||coverage.globalLimited||coverage.limitedPrefixes.some(prefix=>contains(file,prefix)||contains(prefix,file));
+  function discardTree(file){const previous=trees.get(file);if(previous){trees.delete(file);treeBytes-=previous.bytes;}}
+  function uncertain(file,reason){
+    discardTree(file);
+    if(diagnostics.get(file)!==reason){
+      diagnostics.delete(file);diagnostics.set(file,reason);while(diagnostics.size>32)diagnostics.delete(diagnostics.keys().next().value);
+      onUncertainDirectory({directory:file.slice(0,256),reason});
+    }
+    return Object.assign(Error(`Cannot verify a coalesced directory change in ${file.slice(0,256)} (${reason}). The previous build is kept. Run a full build or narrow generated inputs before retrying.`),{code:'PRNEXT_RECURSIVE_CHANGE_UNVERIFIED'});
+  }
+  async function treeSnapshot(relative){
+    const observed=new Map();let entriesRead=0,retainedBytes=relative.length*2+128;
+    const incomplete=reason=>{throw Object.assign(Error('Incomplete recursive source snapshot'),{snapshotReason:reason});};
+    async function visit(name){
+      const file=path.join(root,name),before=await lstat(file);let value,semantic;
+      if(before.isSymbolicLink())incomplete('symbolic-link');
+      if(before.isDirectory()){
+        const entries=[],directory=await opendir(file);
+        for await(const entry of directory){if(++entriesRead>maxTreeEntries)incomplete('entry-capacity');entries.push(entry);}
+        value=directoryFingerprint(entries);
+        const watched=entries.filter(entry=>allowed(name+'/'+entry.name));semantic=directoryFingerprint(watched);
+        rememberObserved(name,value,semantic);
+        for(const entry of watched)await visit(name+'/'+entry.name);
+      }else if(before.isFile()){
+        const hash=createHash('sha256');for await(const chunk of createReadStream(file,{highWaterMark:64*1024}))hash.update(chunk);
+        value='file:'+hash.digest('hex');rememberObserved(name,value,value);
+      }else incomplete('special-file');
+      const after=await lstat(file);
+      if(before.dev!==after.dev||before.ino!==after.ino||before.size!==after.size||before.mtimeMs!==after.mtimeMs||before.ctimeMs!==after.ctimeMs)incomplete('changed-during-read');
+    }
+    function rememberObserved(file,value,semantic){
+      retainedBytes+=2*(file.length+value.length+semantic.length)+96;
+      if(observed.size>=maxTreeEntries||retainedBytes>maxTreeBytes)incomplete('memory-capacity');
+      observed.set(file,{value,semantic});
+    }
+    try{
+      await visit(relative);const hash=createHash('sha256');
+      for(const [file,value]of [...observed].sort(([a],[b])=>a.localeCompare(b)))hash.update(JSON.stringify([file,value.semantic]));
+      return {complete:true,observed,digest:hash.digest('hex'),bytes:retainedBytes};
+    }catch(error){return {complete:false,reason:error.snapshotReason||'read-failure'};}
+  }
+  function retainTree(file,snapshot){
+    discardTree(file);
+    while(trees.size&&(trees.size>=32||treeBytes+snapshot.bytes>maxTreeBytes))discardTree(trees.keys().next().value);
+    trees.set(file,snapshot);treeBytes+=snapshot.bytes;
+  }
+  function observeTree(file,snapshot){
+    for(const [name,previous]of [...fingerprints])if(contains(file,name)&&allowed(name)&&!snapshot.observed.has(name)&&previous.value!=='missing')remember(name,'missing');
+    for(const [name,value]of consumedInputs)if(contains(file,name)&&allowed(name)&&snapshot.observed.get(name)?.value!==value)consumedInputs.delete(name);
+    for(const [directory,previous]of trees){
+      if(!contains(file,directory)&&!contains(directory,file))continue;
+      const same=[...previous.observed].every(([name,value])=>!contains(file,name)||snapshot.observed.get(name)?.semantic===value.semantic)
+        &&[...snapshot.observed].every(([name,value])=>!contains(directory,name)||previous.observed.get(name)?.semantic===value.semantic);
+      if(!same)discardTree(directory);
+    }
+  }
+  function observePath(file,value){
+    for(const [directory,snapshot]of trees){
+      if(contains(directory,file)){
+        const observed=snapshot.observed.get(file);
+        if(value===undefined||(value==='missing'?observed!==undefined:observed?.value!==value))discardTree(directory);
+      }else if(contains(file,directory))discardTree(directory);
+    }
+    for(const [name,previous]of consumedInputs)if(contains(file,name)&&(name!==file||previous!==value))consumedInputs.delete(name);
+    if(!value?.startsWith('directory:'))for(const [name]of [...fingerprints])if(name!==file&&contains(file,name))remember(name,value===undefined?undefined:'missing');
+  }
   let bytes=0;
   function remember(file,value) {
     const previous=fingerprints.get(file);
@@ -99,12 +187,39 @@ export function createDevChangeFilter(root, {maxEntries=512,maxBytes=1024*1024}=
   const filter=async files => {
     const changed=[];
     for (const file of files) {
+      if(directoryEventsAreRecursive&&allowed(file)){
+        let directory=false;try{directory=(await stat(path.join(root,file))).isDirectory();}catch{}
+        if(directory){
+          const snapshot=await treeSnapshot(file);
+          if(!snapshot.complete)throw uncertain(file,snapshot.reason);
+          if(limitedFor(file))throw uncertain(file,'input-coverage');
+          observeTree(file,snapshot);
+          const previous=trees.get(file);
+          const consumed=[...snapshot.observed].every(([name,value])=>consumedInputs.get(name)===value.value)
+            &&[...consumedInputs].every(([name,value])=>!contains(file,name)||!allowed(name)||!value.startsWith('file:')||snapshot.observed.has(name));
+          if((!previous||previous.digest!==snapshot.digest)&&!consumed)changed.push(file);
+          retainTree(file,snapshot);
+          diagnostics.delete(file);
+          continue;
+        }
+      }
       const value=await fingerprint(file), previous=fingerprints.get(file);
+      if(directoryEventsAreRecursive)observePath(file,value);
       if (value===undefined || !previous || previous.value!==value) changed.push(file);
       remember(file,value);
     }
     return changed;
   };
-  filter.acceptInputs=inputs=>{const changed=[];for(const [file,value] of inputs){if(fingerprints.get(file)?.value!==value)changed.push(file);remember(file,value);}return changed;};
+  filter.acceptInputs=inputs=>{
+    coverage=inputs.find(entry=>entry[2]?.version===1)?.[2];
+    // Only the latest bounded compiler receipt can acknowledge an uncached
+    // subtree. Event deduplication may keep older values in its independent LRU.
+    consumedInputs=new Map();for(const [file,value]of inputs)if(typeof file==='string'&&typeof value==='string')consumedInputs.set(file,value);
+    for(const [directory,snapshot]of trees){
+      if(limitedFor(directory)||inputs.some(([file,value])=>typeof file==='string'&&contains(directory,file)&&allowed(file)&&(value===null||snapshot.observed.get(file)?.value!==value)))discardTree(directory);
+    }
+    const changed=[];for(const [file,value] of inputs){if(typeof file!=='string')continue;if(fingerprints.get(file)?.value!==value)changed.push(file);remember(file,value);}return changed;
+  };
+  filter.recursiveDiagnostics=()=>[...diagnostics].map(([directory,reason])=>({directory,reason}));
   return filter;
 }

package/runtime/dev-indicator.mjs

@@ -1,10 +1,15 @@
 import logo from './dev-logo.mjs';
-import { createLazyDevTool } from './dev-lazy-tool.mjs';
+import { createLazyDevTool, registerDevToolLoaders } from './dev-lazy-tool.mjs';
 import { popoutIcon } from './dev-popout.mjs';
 import { deviceIcons } from './dev-ui-icons.mjs';
 import { createDevPosition } from './dev-position.mjs';
 import { createDevIssueMotion } from './dev-issue-motion.mjs';
 
+const loadDevTool = registerDevToolLoaders({
+  workbench: () => import('./dev-workbench.mjs'),
+  inspector: () => import('./dev-tools-panel.mjs'),
+});
+
 // This module is imported only by the development browser entry. No framework
 // contexts, application CSS, network requests or additional SSE streams.
 export function createDevIndicator({ position = 'bottom-left', snapshot, showIssues, capture, tools }) {
@@ -79,7 +84,7 @@ export function createDevIndicator({ position = 'bottom-left', snapshot, showIss
   let workbench;
   const toolError=error=>{feedback.textContent='Could not open development tool. Try again.';console.error(error);};
   const getWorkbench = () => workbench ||= createLazyDevTool(async()=>{
-    const {createDevWorkbench}=await import('./dev-workbench.mjs');
+    const {createDevWorkbench}=await loadDevTool('workbench');
     return createDevWorkbench({shadow,capture,tools,restoreFocus:()=>trigger.focus()});
   },{onError:toolError,reserve(method,args){
     if(!['popConsole','popPreview'].includes(method))return;
@@ -94,7 +99,7 @@ export function createDevIndicator({ position = 'bottom-left', snapshot, showIss
   consoleRow.append(consoleAction,detachButton('Open console in new window',()=>{close(false);getWorkbench().popConsole();}));
   let inspector;
   const getInspector = () => inspector ||= createLazyDevTool(async()=>{
-    const {createDevToolsPanel}=await import('./dev-tools-panel.mjs');
+    const {createDevToolsPanel}=await loadDevTool('inspector');
     return createDevToolsPanel({shadow,tools,restoreFocus:()=>trigger.focus()});
   },{onError:toolError});
   if (tools) {

package/runtime/dev-lazy-imports.mjs

@@ -0,0 +1,121 @@
+import path from 'node:path';
+import {constants} from 'node:fs';
+import {readdir,readFile,writeFile,stat,lstat,open,mkdtemp,link,rm} from 'node:fs/promises';
+
+export const MAX_LAZY_ASSET_BYTES=128*1024*1024;
+export const MAX_LAZY_ASSET_FILES=16384;
+const token=/^\/_prnext\/lazy\/([a-f0-9]{24})$/;
+export function lazyImportIdentifier(raw){return token.exec(new URL(raw,'http://local').pathname)?.[1];}
+
+function receiptFiles(receipt,cacheId){
+  if(!receipt||receipt.version!==1||typeof cacheId!=='string'||!cacheId||cacheId.length>256||receipt.baseCacheId!==cacheId||!Array.isArray(receipt.files))throw Error('Invalid or obsolete deferred asset receipt');
+  if(receipt.files.length>MAX_LAZY_ASSET_FILES)throw Error('Deferred import exceeded the asset count budget');
+  const names=new Set(),files=[];let total=0;
+  for(const file of receipt.files){
+    const name=file?.name;
+    if(typeof name!=='string'||!name||name.length>255||!/^[A-Za-z0-9_.-]+$/.test(name)||name==='.'||name==='..'||name.endsWith('.')||/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name)||names.has(name.toLowerCase()))throw Error('Invalid or duplicate deferred asset receipt name');
+    if(!Number.isSafeInteger(file.bytes)||file.bytes<0||file.bytes>MAX_LAZY_ASSET_BYTES||(total+=file.bytes)>MAX_LAZY_ASSET_BYTES)throw Error('Deferred asset receipt exceeded the 128 MiB generation budget');
+    names.add(name.toLowerCase());files.push({name,bytes:file.bytes});
+  }
+  return files;
+}
+
+function regularAsset(info,bytes){
+  if(!info.isFile()||info.isSymbolicLink())throw Error('Invalid deferred asset: expected a regular file without symbolic links');
+  if(info.size!==bytes)throw Error('Deferred asset does not match the receipt byte size');
+  return info;
+}
+
+async function readReceiptAsset(filename,bytes,checked){
+  const expected=checked||regularAsset(await lstat(filename),bytes);
+  const file=await open(filename,constants.O_RDONLY|(constants.O_NOFOLLOW||0));
+  try{
+    const info=regularAsset(await file.stat(),bytes);
+    if(info.dev!==expected.dev||info.ino!==expected.ino)throw Error('Deferred asset changed after receipt validation');
+    // Metadata can race a writer. Read only the declared size plus one byte,
+    // rather than letting readFile allocate for a later, unbounded file size.
+    const data=Buffer.allocUnsafe(bytes);let offset=0;
+    while(offset<bytes){
+      const {bytesRead}=await file.read(data,offset,bytes-offset,offset);
+      if(!bytesRead)throw Error('Deferred asset ended before the receipt byte size');
+      offset+=bytesRead;
+    }
+    if((await file.read(Buffer.allocUnsafe(1),0,1,bytes)).bytesRead)throw Error('Deferred asset exceeded the receipt byte size');
+    return data;
+  }finally{await file.close();}
+}
+
+async function readExistingReceiptAsset(filename,bytes){
+  const info=await lstat(filename);
+  if(!info.isFile()||info.isSymbolicLink())throw Error('Invalid deferred asset: expected a regular file without symbolic links');
+  if(info.size!==bytes)throw Error('Deferred compilation produced a conflicting immutable asset');
+  return readReceiptAsset(filename,bytes,info);
+}
+
+/** Only registered tokens can reach the compiler. The caller serializes builds. */
+export async function materializeDevImport({root,current,id,compile}){
+  const registry=current.manifest.devLazy;
+  if(!registry||!registry.modules.some(item=>item.id===id))throw Error('Unknown deferred import identifier');
+  if(registry.outputs[id])return registry.outputs[id];
+  const built=await compile({id,modules:registry.modules,bridges:registry.bridges,shared:registry.shared});
+  const next=built.devLazy,target=next?.outputs?.[id];
+  if(!target)throw Error('The compiler did not produce the requested deferred import');
+  // New server implementations cannot be added to a running immutable runtime.
+  // Existing Server Action proxies are reused through the static ESM bridges.
+  if(Object.keys(built.app?.actions||{}).some(key=>!Object.hasOwn(current.manifest.app?.actions||{},key)))throw Error('A deferred module introduced a new Server Action. Import that action statically or disable experimental.lazyDynamicImports.');
+  const source=path.join(built.outputDirectory,'assets'),destination=path.join(root,current.directory,'assets');
+  const received=Object.hasOwn(built,'devLazyAssets');
+  const files=received?receiptFiles(built.devLazyAssets,current.manifest.cacheId):await readdir(source,{withFileTypes:true}),pending=[];let bytes=0;
+  if(files.length>MAX_LAZY_ASSET_FILES)throw Error('Deferred import exceeded the asset count budget');
+  if(received){
+    for(const directory of [source,destination]){const info=await lstat(directory);if(!info.isDirectory()||info.isSymbolicLink())throw Error('Invalid deferred asset directory');}
+    // Validate every declared file before reading any payload or publishing.
+    for(const file of files)file.info=regularAsset(await lstat(path.join(source,file.name)),file.bytes);
+  }
+  for(const file of files){
+    if(!received&&(!file.isFile()||file.name!==path.basename(file.name)))throw Error('Invalid deferred asset');
+    if(!received&&(await stat(path.join(source,file.name))).size>MAX_LAZY_ASSET_BYTES)throw Error('Deferred import asset exceeded the 128 MiB generation budget');
+    const data=received?await readReceiptAsset(path.join(source,file.name),file.bytes,file.info):await readFile(path.join(source,file.name));
+    const previous=await(received?readExistingReceiptAsset(path.join(destination,file.name),file.bytes):readFile(path.join(destination,file.name))).catch(error=>{if(error.code!=='ENOENT')throw error;});
+    if(previous){if(!previous.equals(data))throw Error('Deferred compilation produced a conflicting immutable asset');continue;}
+    bytes+=data.length;
+    if(bytes+(current.lazyAssetBytes||0)>MAX_LAZY_ASSET_BYTES)throw Error('Deferred import assets exceeded the 128 MiB generation budget');
+    pending.push([file.name,data]);
+  }
+  if(pending.length){
+    // Partial writes stay outside the served assets directory. A hard link
+    // publishes a complete file atomically and exclusively without replacing an
+    // immutable asset, even if another writer wins between inspection and I/O.
+    const temporary=await mkdtemp(path.join(root,current.directory,'.lazy-publish-'));
+    current.lazyAssetBytes=(current.lazyAssetBytes||0)+bytes;
+    let retained=0,failure;
+    try{
+      for(const [name,data]of pending)await writeFile(path.join(temporary,name),data,{flag:'wx'});
+      for(const [name,data]of pending){
+        // A failed publication can have an uncertain outcome. Keep its charge
+        // conservatively; a retry can reuse a complete asset without recharging.
+        retained+=data.length;
+        try{await link(path.join(temporary,name),path.join(destination,name));}
+        catch(error){
+          if(error.code!=='EEXIST')throw error;
+          const existing=received?await readExistingReceiptAsset(path.join(destination,name),data.length):await readFile(path.join(destination,name));
+          if(!existing.equals(data))throw Error('Deferred compilation produced a conflicting immutable asset');
+          retained-=data.length;
+        }
+      }
+    }catch(error){failure=error;}
+    try{
+      await rm(temporary,{recursive:true,force:true,maxRetries:10,retryDelay:100});
+      // Reclaim only unpublished bytes after deletion of our private staging
+      // files is confirmed. Complete public files are never removed on failure.
+      current.lazyAssetBytes-=bytes-retained;
+    }catch(error){
+      if(failure){failure.cleanupError=error;failure.message+='; deferred asset staging cleanup also failed';}
+      else failure=error;
+    }
+    if(failure)throw failure;
+  }
+  registry.modules=next.modules;registry.bridges=next.bridges;registry.shared=next.shared;
+  Object.assign(registry.outputs,next.outputs);
+  return target;
+}

package/runtime/dev-lazy-staging.mjs

@@ -0,0 +1,14 @@
+import { lstat, realpath, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+/** Delete only an unpublished direct-child stage created by our lazy compiler. */
+export async function discardLazyBuild(root, built) {
+  if (!built?.devLazyTemporary) return;
+  const canonicalRoot = await realpath(root), directory = path.resolve(built.outputDirectory);
+  if (path.dirname(directory) !== canonicalRoot ||
+      !/^\.prnext-build-[a-f0-9-]{36}$/.test(path.basename(directory))) throw Error('Invalid deferred staging directory');
+  const info = await lstat(directory).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  if (!info) return;
+  if (!info.isDirectory() || info.isSymbolicLink() || await realpath(directory) !== directory) throw Error('Invalid deferred staging directory');
+  await rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+}

package/runtime/dev-lazy-tool.mjs

@@ -1,5 +1,21 @@
 // Capture user activation synchronously for detached windows, even on a slow
 // connection. Import failures/disposal close reservations instead of leaking tabs.
+const loaderRegistry = Symbol.for('prnext.dev.tool.loaders');
+
+// The indicator survives Fast Refresh, while hashed import URLs belong to a
+// build generation. Publish the current factories on module evaluation so an
+// older, unopened indicator never requests a retired generation's lazy chunk.
+// Existing tool instances remain owned by createLazyDevTool and keep their DOM.
+export function registerDevToolLoaders(loaders, target = globalThis) {
+  const registry = target[loaderRegistry] ||= Object.create(null);
+  Object.assign(registry, loaders);
+  return name => {
+    const load = registry[name];
+    if (typeof load !== 'function') throw Error('Development tool loader is unavailable.');
+    return load();
+  };
+}
+
 export function createLazyDevTool(load,{onError=console.error,reserve}={}) {
   let instance,pending,disposed=false,epoch=0;
   const get=()=>pending||=(async()=>{const value=await load();if(disposed){value.dispose();throw Error('Development tool was closed');}return instance=value;})().catch(error=>{pending=undefined;throw error;});

package/runtime/dev-style-retention.mjs

@@ -0,0 +1,15 @@
+import {rm} from 'node:fs/promises';
+import path from 'node:path';
+
+// Asset-only generations do not own backend/compiler requests. Drain their
+// asset leases and finish deleting the excess snapshot before announcing ready.
+export async function pruneDevelopmentStyles(generations,gateway,root){
+  while(generations.length>3){
+    const old=generations[0];
+    await gateway.request('retire',{generation:old.id});
+    await gateway.request('forget',{generation:old.id});
+    await rm(path.join(root,old.directory),{recursive:true,force:true,maxRetries:10,retryDelay:100});
+    // Keep failed deletions tracked so a later update can retry their cleanup.
+    generations.shift();
+  }
+}

package/runtime/development.mjs

@@ -1,6 +1,7 @@
+import {createDevCompilerBroker} from './dev-compiler-broker.mjs';
 import {spawn} from 'node:child_process';
 import {mkdir,readdir,readFile,writeFile,rm,link,copyFile,realpath,lstat} from 'node:fs/promises';
-import {randomUUID} from 'node:crypto';
+import {randomUUID,randomBytes} from 'node:crypto';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {rename} from './fs.mjs';
@@ -20,6 +21,10 @@ import {tryDevCssUpdate} from '../build/dev-css-update.mjs';
 import {devBuildReason} from './dev-build-reasons.mjs';
 import {publishDependencyGraph,affectedDependencies,canSkipUnopenedRoutes} from './dev-dependency-graph.mjs';
 import {prepareDevNotification} from './dev-notification.mjs';
+import {writeAtomicFile} from './atomic-file.mjs';
+import {lazyImportIdentifier,materializeDevImport} from './dev-lazy-imports.mjs';
+import {discardLazyBuild} from './dev-lazy-staging.mjs';
+import {pruneDevelopmentStyles} from './dev-style-retention.mjs';
 
 const packageRoot=fileURLToPath(new URL('../',import.meta.url));
 export function developmentRoute(routes,raw,config={}) {
@@ -82,6 +87,9 @@ export async function develop(projectRoot,args,binary) {
 }
 async function runDevelopment(projectRoot,args,binary) {
   const root=await realpath(projectRoot),options=serverOptions(args),session=randomUUID();
+  // Private IPC state survives compiler recycling without exposing the key in
+  // the browser's session metadata or any development manifest/notification.
+  const devActionSecret=randomBytes(32).toString('base64');
   const stateFile=path.join(root,'.prnext-dev.json'),home=path.join(root,'.prnext-dev',session);
   const diagnosticsDirectory=process.env.PRNEXT_INSPECT_DIR||path.join(home,'diagnostics');
   // The session is ours; never clean a path obtained from application config.
@@ -94,8 +102,19 @@ async function runDevelopment(projectRoot,args,binary) {
   const lifecycle=new AbortController();
   let queue=Promise.resolve(),stateQueue=Promise.resolve(),output='.prnext',changes=new Set(),active=new Map(),failed=new Set();
   const failedPaths=new Set();
-  const generations=[],styleGenerations=[],retiring=new Set(),pins=new Map(),routeCache=new Map(),filter=createDevChangeFilter(root);
-  const runtimePool=createDevRuntimePool({binary,root,home,environment:{PRNEXT_INSPECT_DIR:diagnosticsDirectory,...(options.profile?{PRNEXT_PROFILE:options.profile}:{})},onChild:child=>captureOutput({stderr:child.stderr,once:child.once.bind(child)},'runtime',{forwardStdout:false})});
+  const requestedImports=new Set();
+  const generations=[],styleGenerations=[],retiring=new Set(),pins=new Map(),routeCache=new Map(),filter=createDevChangeFilter(root,{directoryEventsAreRecursive:process.platform==='darwin',ignore:relative=>relative===output||relative.startsWith(output+'/')});
+  const compilerBroker=await createDevCompilerBroker({compile:(pattern,sources)=>serialized(async()=>{
+    if(stopping)throw Error('Development is stopping');
+    if(!discovery)await discover();
+    const patterns=[...new Set([pattern,...sources])];
+    if(patterns.some(p=>!discovery.project.routes.some(route=>route.pattern===p)))await discover();
+    if(patterns.some(p=>!discovery.project.routes.some(route=>route.pattern===p)))throw Error('Unknown deferred route pattern');
+    for(const value of patterns)active.set(value,Date.now());
+    if(!current||patterns.some(p=>!current.patterns.has(p)))await rebuild([...active.keys()]);
+    return current.directory;
+  })});
+  const runtimePool=createDevRuntimePool({binary,root,home,environment:{PRNEXT_DEV_COMPILER:compilerBroker.descriptor,PRNEXT_INSPECT_DIR:diagnosticsDirectory,...(options.profile?{PRNEXT_PROFILE:options.profile}:{})},onChild:child=>captureOutput({stderr:child.stderr,once:child.once.bind(child)},'runtime',{forwardStdout:false})});
   const toolSnapshot=()=>({...readyState,safeMode:options.safe,sequence:readyState.sequence??sequence,session,typeErrors,
     routes:(discovery?.project.routes||[]).filter(route=>!route.internal).map(route=>({path:(discovery.config.basePath||'')+(route.pattern==='/'?'/':route.pattern),kind:route.kind,source:route.file?path.relative(root,route.file).replaceAll(path.sep,'/'):undefined,compiled:current?.patterns.has(route.pattern)||false,pinned:[...pins.values()].some(pin=>pin.pattern===route.pattern)})),
     cache:{activeRoutes:active.size,pinnedRoutes:new Set([...pins.values()].map(pin=>pin.pattern)).size,retainedGenerations:generations.length,lookupEntries:routeCache.size,compiler:readyState.compiler,transforms:readyState.transforms,persistentTransforms:true,dependencyIndex:dependencyIndexValid?{valid:true,...current?.manifest.devDependencyIndex}:{valid:false}}});
@@ -113,10 +132,23 @@ async function runDevelopment(projectRoot,args,binary) {
     const route=developmentRoute(discovery.project.routes,raw,discovery.config);
     if(routeCache.size>=256)routeCache.delete(routeCache.keys().next().value);routeCache.set(key,route);return route;
   }
+  let publicationFailures=0,lastPublicationFailure;
   const writeState=value=>{
-    const task=stateQueue.then(async()=>{if(value)readyState=value;const temporary=stateFile+'.'+randomUUID()+'.tmp';
-      const {notification,text}=prepareDevNotification({...readyState,safeMode:options.safe,typeErrors});
-      try{await writeFile(temporary,text);await rename(temporary,stateFile);if(gateway&&!gateway.stopping)await gateway.request('notify',{value:notification});}finally{await rm(temporary,{force:true});}});
+    const task=stateQueue.then(async()=>{
+      const next=value||readyState;
+      const {notification,text}=prepareDevNotification({...next,safeMode:options.safe,typeErrors,...(publicationFailures?{publication:{failures:publicationFailures,lastFailure:lastPublicationFailure}}:{})});
+      try{await writeAtomicFile(stateFile,text);}
+      catch(error){
+        publicationFailures++;lastPublicationFailure=error.atomicFile||{operation:'publish-development-state',code:error.code||'UNKNOWN'};
+        // A failed publication must leave the last complete state readable.
+        // This private bounded receipt contains no source path or payload.
+        await writeFile(path.join(diagnosticsDirectory,'state-publication.json'),JSON.stringify({failures:publicationFailures,lastFailure:lastPublicationFailure,lastSuccessfulSequence:readyState.sequence??null})+'\n',{mode:0o600}).catch(()=>{});
+        tools?.addServerLog('error','Development state publication failed.',{process:'compiler',...lastPublicationFailure});
+        throw error;
+      }
+      readyState=next;
+      if(gateway&&!gateway.stopping)await gateway.request('notify',{value:notification});
+    });
     stateQueue=task.catch(()=>{});return task;
   };
   const serialized=run=>{const task=queue.then(()=>{if(stopping)throw Error('Development is stopping');return run();});queue=task.catch(()=>{});return task;};
@@ -140,14 +172,13 @@ async function runDevelopment(projectRoot,args,binary) {
   async function discover(){
     discovery=(await compilerRequest('discover')).discovery;routeCache.clear();output=discovery.config.distDir;
     if(options.safe)discovery={...discovery,eager:true};
-    if(discovery.eager&&!options.safe)console.log('Development uses the complete route graph for middleware, rewrites or parallel routing.');
     const {writeTypedRoutes}=await import('../build/typed-routes.mjs');
     await writeTypedRoutes(root,discovery.project,discovery.config);
     if(!typeChecker||typeChecker.inactive){const {startTypeChecker}=await import('../build/typescript-dev.mjs');typeChecker=await startTypeChecker(root,discovery.config,errors=>{typeErrors=errors;if(!stopping)void writeState().catch(console.error);});}
   }
   async function launch(manifest,directory){
     const runtime=options.safe?undefined:await runtimePool.take(directory).catch(error=>{tools?.addServerLog('warn','Worker warmup was unavailable; starting a fresh worker.',{process:'runtime'});return undefined;});
-    const env={...process.env,NODE_ENV:process.env.NODE_ENV||'development',PRNEXT_INSPECT_DIR:diagnosticsDirectory};
+    const env={...process.env,NODE_ENV:process.env.NODE_ENV||'development',PRNEXT_INSPECT_DIR:diagnosticsDirectory,PRNEXT_DEV_COMPILER:compilerBroker.descriptor};
     delete env.PRNEXT_DEV_BROKER;
     if(runtime)env.PRNEXT_DEV_BROKER=runtime.descriptor;
     const child=spawn(binary,['start',root,'--build-dir',directory,'--worker',path.join(root,directory,'runtime/worker.mjs'),'--node',process.execPath,'--hostname','127.0.0.1','--port','0','--shutdown-on-stdin-eof',...options.backend],{stdio:['pipe','pipe','pipe'],windowsHide:true,env});
@@ -170,21 +201,21 @@ async function runDevelopment(projectRoot,args,binary) {
       if(!options.safe)void runtimePool.warm().catch(()=>{});
       if(current&&!discovery.eager&&discovery.cssFast){
         const directory=path.relative(root,path.join(home,'styles-'+randomUUID())).replaceAll(path.sep,'/');
-        const styles=await tryDevCssUpdate({root,source:path.join(root,current.cssDirectory||current.directory),destination:path.join(root,directory),manifest:current.manifest,changed:changedFiles,sequence:sequence+1,cssEngine:discovery.config.cssEngine,snapshot,onFallback:code=>{reason=devBuildReason({changed:changedFiles,cause:code});}});
+        const styles=await tryDevCssUpdate({root,source:path.join(root,current.cssDirectory||current.directory),baseSource:path.join(root,current.directory),destination:path.join(root,directory),manifest:current.manifest,changed:changedFiles,sequence:sequence+1,cssEngine:discovery.config.cssEngine,onFallback:code=>{reason=devBuildReason({changed:changedFiles,cause:code});}});
         if(styles){
           await gateway.request('assets',{generation:styles.buildId,directory});
           try{styles.devDependencyIndex=await publishDependencyGraph(gateway,styles);dependencyIndexValid=true;}catch(error){dependencyIndexValid=false;await gateway.request('graph',{routes:[]});tools?.addServerLog('warn','Selective HMR unavailable: '+error.message,{process:'compiler'});}
-          sequence++;current.manifest=styles;current.cssDirectory=directory;current.cssOnly=true;current.affectedRoutes=undefined;current.changed=changed;
           styleGenerations.push({id:styles.buildId,directory});
+          await pruneDevelopmentStyles(styleGenerations,gateway,root);
+          sequence++;current.manifest=styles;current.cssDirectory=directory;current.cssOnly=true;current.affectedRoutes=undefined;current.changed=changed;
           reason=devBuildReason({cause:'css-only'});
           await writeState({state:'ready',reason,buildId:styles.buildId,clientManifest:styles.devClient,sequence,session,changed,cssOnly:true,listenerPid:gateway.child.pid,compiler:current.compiler,transforms:current.transforms});
           tools?.recordBuild({buildId:styles.buildId,reason:reason.summary,reasonCode:reason.code,sequence,time:Date.now(),startedAt,duration:performance.now()-started,phases:{styles:performance.now()-started},mode:'css',state:'ready'});
           console.log('Styles updated. '+reason.summary);
-          while(styleGenerations.length>3){const old=styleGenerations.shift();await gateway.request('retire',{generation:old.id});await gateway.request('forget',{generation:old.id});await rm(path.join(root,old.directory),{recursive:true,force:true,maxRetries:10,retryDelay:100});}
           await watcher?.refresh();return styles;
         }
       }
-      const result=await compilerRequest('build',{options:{...(discovery.eager?{}:{devRoutes:patterns}),devSafe:options.safe,devSequence:++sequence,devSession:session,devTools:tools?.bootstrap,devAffectedModules:affectedModules,devForceRefresh:options.safe||changedFiles.some(file=>/\.(?:css|scss|sass)$/.test(file)||/(?:postcss|browserslist|\.env|config)/.test(file))}});
+      const result=await compilerRequest('build',{options:{...(discovery.eager?{}:{devRoutes:patterns}),devSafe:options.safe,devSequence:++sequence,devSession:session,devActionSecret,devTools:tools?.bootstrap,devAffectedModules:affectedModules,devLazyActivated:[...requestedImports],devForceRefresh:options.safe||changedFiles.some(file=>/\.(?:css|scss|sass)$/.test(file)||/(?:postcss|browserslist|\.env|config)/.test(file))}});
       phases.compile=performance.now()-mark;mark=performance.now();
       if(stopping)throw Error('Development is stopping');
       const consumed=filter.acceptInputs(result.inputs||[]);
@@ -201,32 +232,57 @@ async function runDevelopment(projectRoot,args,binary) {
       catch(error){dependencyIndexValid=false;await gateway.request('graph',{routes:[]});affectedRoutes=undefined;affectedModules=undefined;tools?.addServerLog('warn','Selective HMR unavailable: '+error.message,{process:'compiler'});}
       const previous=current;current=next;current.compiler=result.compiler;current.transforms=result.transforms;generations.push(next);failed.clear();failedPaths.clear();
       current.manifest=manifest;current.changed=changed;current.patterns=new Set(discovery.eager?discovery.project.routes.map(route=>route.pattern):patterns);
+      for(const id of requestedImports)if(!manifest.devLazy?.modules.some(item=>item.id===id))requestedImports.delete(id);
       const affected=Object.keys(manifest.app?.actions||{}).length?undefined:affectedRoutes;
       current.affectedRoutes=affected;
-      await writeState({state:'ready',reason,buildId:manifest.buildId,clientManifest:manifest.devClient,sequence:manifest.devSequence,session,changed,affectedRoutes:affected,listenerPid:gateway.child.pid,compiler:result.compiler,transforms:result.transforms,routes:manifest.routes.filter(route=>!route.internal).map(route=>route.pattern)});
-      tools?.recordBuild({buildId:manifest.buildId,reason:reason.summary,reasonCode:reason.code,sequence:manifest.devSequence,time:Date.now(),startedAt,duration:performance.now()-started,phases,routes:patterns.length,state:'ready'});
-      console.log('Source compiled. '+reason.summary);
-      if(previous){
-        const retiringTask=(async()=>{await gateway.request('retire',{generation:previous.id}).catch(()=>{});await previous.runtime?.close();await stop(previous.child);})().finally(()=>retiring.delete(retiringTask));retiring.add(retiringTask);
+      try{
+        await writeState({state:'ready',reason,buildId:manifest.buildId,clientManifest:manifest.devClient,sequence:manifest.devSequence,session,changed,affectedRoutes:affected,listenerPid:gateway.child.pid,compiler:result.compiler,transforms:result.transforms,routes:manifest.routes.filter(route=>!route.internal&&!route.devDeferred).map(route=>route.pattern)});
+        tools?.recordBuild({buildId:manifest.buildId,reason:reason.summary,reasonCode:reason.code,sequence:manifest.devSequence,time:Date.now(),startedAt,duration:performance.now()-started,phases,routes:patterns.length,state:'ready'});
+        console.log('Source compiled. '+reason.summary);
+      }finally{
+        // Activation already succeeded. A locked readiness receipt must not
+        // keep obsolete runtimes alive or bypass the generation bound. Retire
+        // through the gateway so existing requests drain before their owner
+        // closes; the newly activated current runtime remains available.
+        if(previous){
+          const retiringTask=(async()=>{await gateway.request('retire',{generation:previous.id}).catch(()=>{});await previous.runtime?.close();await stop(previous.child);})().finally(()=>retiring.delete(retiringTask));retiring.add(retiringTask);
+        }
+        while(generations.length>3){const old=generations.shift();
+          // A deferred request may itself be awaiting this build. Never wait for
+          // its generation lease while holding the serialized compiler queue.
+          const cleanup=(async()=>{await gateway.request('retire',{generation:old.id});await old.runtime?.close();await stop(old.child);await gateway.request('forget',{generation:old.id});await rm(path.join(root,old.directory),{recursive:true,force:true,maxRetries:10,retryDelay:100});})().catch(error=>{if(!stopping)console.warn('Development generation cleanup: '+error.message);}).finally(()=>retiring.delete(cleanup));retiring.add(cleanup);
+        }
       }
-      while(generations.length>3){const old=generations.shift();await gateway.request('retire',{generation:old.id});await old.runtime?.close();await stop(old.child);await gateway.request('forget',{generation:old.id});await rm(path.join(root,old.directory),{recursive:true,force:true,maxRetries:10,retryDelay:100});}
       await watcher?.refresh();
       return manifest;
     }catch(error){if(!stopping){tools?.recordBuild({sequence,reason:reason.summary,reasonCode:reason.code,time:Date.now(),startedAt,duration:performance.now()-started,phases,state:'error'});tools?.addServerLog('error',error.message,{process:'compiler'});console.error('Build failed: '+error.message);await writeState({state:'error',reason,error:error.message});}throw error;}
   }
   const updateInfo=()=>({buildId:current.manifest.buildId,clientManifest:current.manifest.devClient,pagesManifest:current.manifest.pagesManifest,sequence:current.manifest.devSequence,session,changed:current.changed,cssOnly:current.cssOnly,affectedRoutes:current.affectedRoutes});
-  async function ensure(raw,client){
-    const warm=discovery&&findRoute(raw);
+  async function ensure(raw,client,exact=false){
+    if(new URL(raw,'http://local').pathname.startsWith('/_prnext/lazy/'))return serialized(async()=>{
+      const id=lazyImportIdentifier(raw);
+      if(!id||!current)throw Error('Unknown deferred import identifier');
+      let built,failure,lazy;
+      try{lazy=await materializeDevImport({root,current,id,compile:async request=>{
+        const result=await compilerRequest('build',{options:{devRoutes:[...current.patterns],devSafe:options.safe,devSequence:sequence,devSession:session,devActionSecret,devTools:tools?.bootstrap,devLazyRequest:request,devLazyBase:{cacheId:current.manifest.cacheId}}});
+        built=result.manifest;return built;
+      }});}catch(error){failure=error;throw error;}
+      finally{try{await discardLazyBuild(root,built);}catch(error){if(failure){failure.cleanupError=error;failure.message+='; deferred compiler staging cleanup also failed';}else throw error;}}
+      requestedImports.add(id);
+      return {lazy};
+    });
+    const resolve=()=>exact?discovery.project.routes.find(route=>route.pattern===raw):findRoute(raw);
+    const warm=discovery&&resolve();
     if(!stopping&&current&&warm&&active.has(warm.pattern)&&current.patterns.has(warm.pattern)){
       active.set(warm.pattern,Date.now());if(pins.has(client))pins.get(client).pattern=warm.pattern;
       return updateInfo();
     }
     return serialized(async()=>{
     if(!discovery)try{await discover();}catch(error){failedPaths.add(raw);await writeState({state:'error',error:error.message});throw error;}
-    let route=findRoute(raw);
+    let route=resolve();
     // A newly written route can be requested before the watcher's debounce.
     // Resolve that miss against the filesystem instead of returning a stale 404.
-    if(!route){await discover();route=findRoute(raw);}
+    if(!route){await discover();route=resolve();}
     if(route)active.set(route.pattern,Date.now());
     if(route&&pins.has(client))pins.get(client).pattern=route.pattern;
     const max=Math.max(0,Math.min(64,discovery.config.onDemandEntries?.pagesBufferLength??5));
@@ -235,7 +291,8 @@ async function runDevelopment(projectRoot,args,binary) {
     const inactive=[...active].filter(([pattern])=>!pinned.has(pattern)).sort((a,b)=>a[1]-b[1]);
     const age=Math.min(86400000,discovery.config.onDemandEntries?.maxInactiveAge??60000);
     while(inactive.length>max&&(Date.now()-inactive[0][1]>=age||active.size>64+pinned.size))active.delete(inactive.shift()[0]);
-    if(!current || route&&!current.patterns.has(route.pattern)){
+    const graphChanged=current&&discovery.project.routes.some(candidate=>!current.manifest.routes.some(built=>built.id===candidate.id));
+    if(!current || graphChanged || route&&!current.patterns.has(route.pattern)){
       try{await rebuild([...active.keys()]);}catch(error){if(route){failed.add(route.pattern);active.delete(route.pattern);}throw error;}
     }
     return updateInfo();
@@ -273,7 +330,7 @@ async function runDevelopment(projectRoot,args,binary) {
       // Node process has drained after() work and cache fills on stdin EOF.
       await runtimePool.close();
       await Promise.all([tools?.close(),...generations.map(g=>stop(g.child)),...retiring]);
-      await queue.catch(()=>{});await stateQueue;await rm(home,{recursive:true,force:true,maxRetries:10,retryDelay:100});await rm(stateFile,{force:true});
+      await queue.catch(()=>{});await compilerBroker.close();await stateQueue;await rm(home,{recursive:true,force:true,maxRetries:10,retryDelay:100});await rm(stateFile,{force:true});
     })();return closing;
   };
   const fatal=error=>{if(!stopping){console.error(error.message);process.exitCode=1;void shutdown();}};
@@ -298,7 +355,8 @@ async function runDevelopment(projectRoot,args,binary) {
     }
     console.log(`PRNext development · http://${options.hostname.includes(':')?'['+options.hostname+']':options.hostname}:${listener.port} · on-demand routes`);
     if(options.safe)console.log('Safe mode: full route builds, fresh compilers and no worker warmup.');
-    watcher=await watchProject(root,{ignore:relative=>relative===output||relative.startsWith(output+'/'),onError:fatal,onChange:file=>{
+    watcher=await watchProject(root,{ignore:relative=>relative===output||relative.startsWith(output+'/'),onError:fatal,onChange:(file,event)=>{
+      typeChecker?.invalidate?.(file,event);
       if(stopping||!shouldWatchProjectFile(file))return;changes.add(String(file).replaceAll(path.sep,'/'));clearTimeout(timer);timer=setTimeout(()=>void serialized(changed).catch(()=>{}),75);
     }});
     await serialized(discover).catch(async error=>{console.error('Build failed: '+error.message);await writeState({state:'error',error:error.message});});