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

package/runtime/app-client.mjs

@@ -39,7 +39,9 @@ function loadClientModule(source) {
 // supplies ESM import functions so React and application contexts stay shared.
 export function installFlightModuleLoader(clientModules) {
   const loaded = new Map();
+  const loadedVersions = new Map();
   const pending = new Map();
+  let version = 0;
   const previousRequire = globalThis.__webpack_require__;
   const previousLoad = globalThis.__webpack_chunk_load__;
   globalThis.__webpack_require__ = id => {
@@ -52,32 +54,42 @@ export function installFlightModuleLoader(clientModules) {
     return typeof source === 'string' ? source : source?.browserModule || String(id);
   };
   globalThis.__webpack_get_script_filename__ = id => globalThis.__webpack_require__.u(id);
-  globalThis.__webpack_chunk_load__ = id => {
-    if (loaded.has(id)) return Promise.resolve();
+  function loadChunk(id) {
     if (pending.has(id)) return pending.get(id);
+    if (loaded.has(id) && loadedVersions.get(id) === version) return Promise.resolve();
     if (!Object.hasOwn(clientModules, id)) {
       if (previousLoad) return previousLoad(id);
       return Promise.reject(new Error(`Unknown PRNext client module ${id}`));
     }
     const source = clientModules[id];
+    const requestedVersion = version;
+    const current = () => {
+      if (!Object.hasOwn(clientModules, id)) throw new Error(`Unknown PRNext client module ${id}`);
+      return loadChunk(id);
+    };
     const promise = Promise.resolve().then(() => loadClientModule(source))
-      .then(module => { loaded.set(id, module); pending.delete(id); }, error => {
-        pending.delete(id);
+      .then(module => {
+        if (requestedVersion !== version) return current();
+        loaded.set(id, module); loadedVersions.set(id, version);
+      }, error => {
+        if (requestedVersion !== version) return current();
+        loaded.delete(id); loadedVersions.delete(id);
         throw error;
+      }).finally(() => {
+        if (pending.get(id) === promise) pending.delete(id);
       });
     pending.set(id, promise);
     return promise;
-  };
+  }
+  globalThis.__webpack_chunk_load__ = loadChunk;
   return {
     async updateModules(nextModules) {
-      const ids = [...loaded.keys()].filter(id => Object.hasOwn(nextModules, id));
+      const ids = [...new Set([...loaded.keys(), ...pending.keys()])].filter(id => Object.hasOwn(nextModules, id));
+      version++;
       clientModules = nextModules;
-      await Promise.all(ids.map(async id => {
-        const source = clientModules[id];
-        const module = await loadClientModule(source);
-        loaded.set(id, module);
-      }));
-      for (const id of loaded.keys()) if (!Object.hasOwn(nextModules, id)) loaded.delete(id);
+      pending.clear();
+      for (const id of loaded.keys()) if (!Object.hasOwn(nextModules, id)) { loaded.delete(id); loadedVersions.delete(id); }
+      await Promise.all(ids.map(loadChunk));
     },
   };
 }
@@ -238,12 +250,18 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   if (initialRewrite) initialModel.rewrite = initialRewrite;
   let currentUrl = new URL(window.location.href);
   let currentRouting = initialModel.routing;
+  // A pending destination may already own the history entry while React still
+  // shows the previous view. Rolling back its render must not rewrite that
+  // entry with the previous view's routing state on the next scroll event.
+  let historyRouting = currentRouting;
   let currentModel = initialModel;
+  let committedView = { model: initialModel, routing: currentRouting, url: currentUrl.href };
+  let pendingView;
   const historyFocus = new Map();
   let currentKey = window.history.state?.__prnext?.key || 0;
   let nextKey = currentKey + 1;
   let navigation = 0;
-  let activeRequest, finishNavigation, pageHidden = false, notifyingPrefetch = false;
+  let activeRequest, finishNavigation, finishCommit, pageHidden = false, notifyingPrefetch = false;
   const prefetches = new Map(), scheduler = createPrefetchScheduler();
   const partialSegments = (typeof __PRNEXT_CACHE_COMPONENTS__ === 'undefined' ? cacheComponents : __PRNEXT_CACHE_COMPONENTS__) ? new Map() : null;
   let segmentBytes = 0;
@@ -254,12 +272,38 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   function saveScroll() {
     // popstate has already changed location; never overwrite its destination.
     if (window.location.href === currentUrl.href) {
-      window.history.replaceState(historyState(currentKey, [window.scrollX, window.scrollY], currentRouting), '', currentUrl.href);
+      window.history.replaceState(historyState(currentKey, [window.scrollX, window.scrollY], historyRouting), '', currentUrl.href);
       if (typeof WeakRef !== 'undefined' && document.activeElement && document.activeElement !== document.body) historyFocus.set(currentKey, new WeakRef(document.activeElement));
       while (historyFocus.size > 16) historyFocus.delete(historyFocus.keys().next().value);
     }
   }
 
+  function renderView(model, url, { token = navigation, canonical = true, committed } = {}) {
+    const view = { model, token };
+    pendingView = view;
+    startTransition(() => root.render(appView({ model, controller, url, globalErrorComponent, globalErrorCss,
+      committed: () => {
+        if (token !== navigation || pendingView !== view) return;
+        pendingView = undefined;
+        // A PPR preview is authorized UI, but not the completed route model
+        // from which a later navigation should inherit its layout cache.
+        if (canonical) committedView = { model, routing: model.routing, url };
+        committed?.();
+      },
+    })));
+  }
+
+  function abandonPendingView() {
+    if (!pendingView) return;
+    pendingView = undefined;
+    currentModel = committedView.model;
+    currentRouting = committedView.routing;
+    // React can already be reading a lazy row after createFromFetch resolves
+    // the root model. Replace that suspended render before abort rejects its
+    // remaining rows; it must not poison the retained layout or page cache.
+    root.render(appView({ model: committedView.model, controller, url: committedView.url, globalErrorComponent, globalErrorCss }));
+  }
+
   const flightTransport = createFlightTransport();
   async function requestFlight(url, signal, routing = currentRouting, onPartial, {skipEnsure=false,fullFlight=false}={}) {
     if(process.env.NODE_ENV==='development'&&!routing?.refresh&&!skipEnsure)await globalThis.__PRNEXT_DEV__?.ensureRoute?.(url.href);
@@ -365,7 +409,10 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   function callServer(id, args) {
     if (!root) return Promise.reject(new Error('Server Actions cannot run during initial rendering'));
     const token = ++navigation;
+    finishCommit?.();
     const target = new URL(window.location.href);
+    saveScroll();
+    abandonPendingView();
     activeRequest?.abort();
     appStyleManager(document).cancel();
     finishNavigation?.(); finishNavigation = undefined;
@@ -384,6 +431,19 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     try { return await performAction(id, args, token, target); } finally { release(); }
   }
 
+  async function waitForDevelopmentUpdate() {
+    // A generation updates the Flight loader before React Refresh registers
+    // the replacement component families. An already-running action may finish
+    // in that interval; rendering its model immediately remounts those client
+    // components and loses layout state. Wait only on development bookkeeping,
+    // never replay the mutation or cancel a newer user navigation.
+    let development = globalThis.__PRNEXT_DEV__;
+    while (development?.applying && development.applied) {
+      await development.applied;
+      development = globalThis.__PRNEXT_DEV__;
+    }
+  }
+
   async function performAction(id, args, token, target) {
     invalidatePrefetches();
     const temporaryReferences = createTemporaryReferenceSet();
@@ -404,15 +464,24 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       throw new Error(`Server Action request failed (${response.status})`);
     }
     const model = await createFromFetch(Promise.resolve(response), { ...flightOptions, temporaryReferences });
+    const outcome = () => {
+      if (model?.actionError) {
+        const error = new Error(model.actionError.message || 'The Server Action failed');
+        if (model.actionError.digest !== undefined) error.digest = model.actionError.digest;
+        throw error;
+      }
+      return model?.actionResult;
+    };
+    if (process.env.NODE_ENV === 'development') await waitForDevelopmentUpdate();
     controller._retentionEpoch++;
     if (model?.routingInvalid || (model?.rootLayout && currentModel.rootLayout && model.rootLayout !== currentModel.rootLayout)) {
       if (token === navigation) window.location.replace(target.href);
-      return model.actionResult;
+      return outcome();
     }
     if (model?.actionRedirect) {
       const destination = navigationUrl(model.actionRedirect.url);
       if (token === navigation) await navigate(destination, { replace: model.actionRedirect.type === 'replace' });
-      return model.actionResult;
+      return outcome();
     }
     if (model && Object.hasOwn(model, 'tree') && token === navigation) {
       assertModel(model);
@@ -421,24 +490,22 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       if (rewrite) model.rewrite = rewrite;
       prepareLayoutCache(model, currentModel);
       try { await appStyleManager(document).prepare(model.globalError ? [] : model.css || []); }
-      catch (error) { if (token !== navigation) return model.actionResult; throw error; }
-      if (token !== navigation) return model.actionResult;
+      catch (error) { if (token !== navigation) return outcome(); throw error; }
+      if (process.env.NODE_ENV === 'development') await waitForDevelopmentUpdate();
+      if (token !== navigation) return outcome();
       currentRouting = model.routing;
       currentModel = model;
+      historyRouting = currentRouting;
       appStyleManager(document).handoff(model.globalError ? [] : model.css || []);
-      startTransition(() => root.render(appView({ model, controller, url: target.href, globalErrorComponent, globalErrorCss })));
-    }
-    if (model?.actionError) {
-      const error = new Error(model.actionError.message || 'The Server Action failed');
-      if (model.actionError.digest !== undefined) error.digest = model.actionError.digest;
-      throw error;
+      renderView(model, target.href, { token });
     }
+    if (model?.actionError) return outcome();
     // Flight's JSON reviver removes object fields encoded as $undefined. A
     // successful void action therefore has an updated tree but no own result.
     if (!model || typeof model !== 'object' || (!Object.hasOwn(model, 'actionResult') && !Object.hasOwn(model, 'tree'))) {
       throw new Error('The Server Action response did not contain a result');
     }
-    return model.actionResult;
+    return outcome();
   }
 
   async function navigate(href, { replace = false, scroll = true, pop = false, savedScroll, savedRouting, refresh = false } = {}) {
@@ -450,13 +517,16 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       return;
     }
     const token = ++navigation;
+    finishCommit?.();
+    saveScroll();
+    abandonPendingView();
     activeRequest?.abort();
     appStyleManager(document).cancel();
     finishNavigation?.(); finishNavigation = undefined;
     activeRequest = undefined;
-    saveScroll();
 
     function updateHistory(destination) {
+      historyRouting = currentRouting;
       if (!pop && !refresh) {
         if (!replace) currentKey = nextKey++;
         const position = scroll ? [0, 0] : [window.scrollX, window.scrollY];
@@ -470,7 +540,9 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       currentUrl = destination;
     }
 
-    if (!refresh && target.pathname === currentUrl.pathname && target.search === currentUrl.search && target.hash !== currentUrl.hash) {
+    const committedUrl = new URL(committedView.url);
+    if (!refresh && target.pathname === currentUrl.pathname && target.search === currentUrl.search && target.hash !== currentUrl.hash &&
+        target.pathname === committedUrl.pathname && target.search === committedUrl.search) {
       updateHistory(target);
       if (scroll) scrollToTarget(target, savedScroll);
       return;
@@ -493,15 +565,11 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
         try { result = await prefetched.promise; }
         catch (error) { if (token !== navigation || (prefetched.abort.signal.aborted && !prefetched.failed)) throw error; result = null; }
         if (result && !result.partial) {
-          if (result.model.authorizationKey) {
-            // A full private prefetch warmed modules/data, not authorization.
-            // HttpOnly cookies may have changed since it was produced.
-            const abort = new AbortController(); activeRequest = abort;
-            result = await navigateFlight(target, abort.signal, pop && savedRouting ? { ...savedRouting, restore: true } : currentRouting);
-          } else {
-            result = { ...result, url: new URL(result.url.href) };
-            if (!result.url.hash) result.url.hash = target.hash;
-          }
+          // Full prefetch warms modules/data, not a future authorization decision.
+          // Static Flight has no authorizationKey, but its proxy checks can still
+          // change when an HttpOnly cookie is revoked before this click.
+          const abort = new AbortController(); activeRequest = abort;
+          result = await navigateFlight(target, abort.signal, pop && savedRouting ? { ...savedRouting, restore: true } : currentRouting);
         } else {
           const preview = result;
           const abort = new AbortController();
@@ -517,7 +585,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
             if (token !== navigation || abort.signal.aborted) return;
             updateHistory(destination); historyUpdated = true;
             appStyleManager(document).handoff(preview.model.css || []);
-            startTransition(() => root.render(appView({ model: preview.model, controller, url: destination.href, globalErrorComponent, globalErrorCss })));
+            renderView(preview.model, destination.href, { token, canonical: false });
           });
         }
       } else {
@@ -536,6 +604,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       if (token !== navigation) return;
       currentRouting = result.model.routing;
       currentModel = result.model;
+      historyRouting = currentRouting;
       if (currentRouting) invalidatePrefetches();
       if (!historyUpdated) updateHistory(result.url);
       const committed = () => {
@@ -546,8 +615,12 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
         }
       };
       appStyleManager(document).handoff(result.model.globalError ? [] : result.model.css || []);
-      if(process.env.NODE_ENV==='development'&&refresh)await new Promise(resolve=>startTransition(()=>root.render(appView({model:result.model,controller,committed:()=>{committed();resolve();},url:result.url.href,globalErrorComponent,globalErrorCss}))));
-      else startTransition(() => root.render(appView({ model: result.model, controller, committed, url: result.url.href, globalErrorComponent, globalErrorCss })));
+      if(process.env.NODE_ENV==='development'&&refresh)await new Promise(resolve=>{
+        const finish=()=>{if(finishCommit===finish)finishCommit=undefined;resolve();};
+        finishCommit=finish;
+        renderView(result.model, result.url.href, { token, committed: () => { committed(); finish(); } });
+      });
+      else renderView(result.model, result.url.href, { token, committed });
     } catch (error) {
       if (token !== navigation || error?.name === 'AbortError') return;
       if(error?.code==='PRNEXT_NAVIGATION_NETWORK'){
@@ -565,9 +638,13 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   }
 
   function purgeRetainedPages() {
+    saveScroll();
+    abandonPendingView();
     controller._retentionEpoch++;
     historyFocus.clear();
-    startTransition(() => root?.render(appView({ model: currentModel, controller, url: currentUrl.href, globalErrorComponent, globalErrorCss })));
+    // This only updates retention for the already committed model. It must
+    // not become a new pending Flight view or a development commit barrier.
+    startTransition(() => root.render(appView({ model: currentModel, controller, url: committedView.url, globalErrorComponent, globalErrorCss })));
   }
 
   const controller = {
@@ -650,7 +727,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   window.addEventListener('popstate', event => {
     void navigate(new URL(window.location.href), { pop: true, savedScroll: event.state?.__prnext?.scroll, savedRouting: event.state?.__prnext?.routing });
   });
-  window.addEventListener('pagehide', () => { saveScroll(); pageHidden = true; navigation++; activeRequest?.abort(); appStyleManager(document).cancel(); finishNavigation?.(); finishNavigation = undefined; invalidatePrefetches(); });
+  window.addEventListener('pagehide', () => { saveScroll(); pageHidden = true; navigation++; finishCommit?.(); abandonPendingView(); activeRequest?.abort(); appStyleManager(document).cancel(); finishNavigation?.(); finishNavigation = undefined; invalidatePrefetches(); });
   window.addEventListener('pageshow', event => { pageHidden = false; if (event.persisted) controller.refresh(); });
   window.addEventListener('prnext:invalidate-navigation', () => { controller._authorizationEpoch++; controller.refresh(); });
   let scrollFrame;
@@ -672,7 +749,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     devStyles: routes => developmentStyles(currentModel, routes).css || [],
     devPrepareStyles: routes => appStyleManager(document).prepare(developmentStyles(currentModel, routes).css || []),
     devStylesApplied: (routes, { commit = true } = {}) => {
-      for (const model of [currentModel]) {
+      for (const model of new Set([currentModel, committedView.model, pendingView?.model].filter(Boolean))) {
         const next = developmentStyles(model, routes);
         model.css = next.css; model.cssScopes = next.cssScopes;
       }

package/runtime/atomic-file.mjs

@@ -0,0 +1,27 @@
+import {open,rm} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {rename} from './fs.mjs';
+
+// The old destination stays readable until the complete replacement exists.
+// Keeping an injectable I/O boundary lets tests exercise real partial-write and
+// rename failures without depending on an antivirus or a physical disk fault.
+export function createAtomicFileWriter({openFile=open,moveFile=rename,removeFile=rm}={}){
+  return async function writeAtomicFile(filename,data){
+    const temporary=filename+'.'+randomUUID()+'.tmp';let file,created=false,failure,phase='create';
+    try{
+      file=await openFile(temporary,'wx',0o600);created=true;phase='write';await file.writeFile(data);phase='close';await file.close();file=undefined;
+      phase='publish';await moveFile(temporary,filename);
+    }catch(error){
+      error.atomicFile={operation:'publish-development-state',phase,code:error.code||'UNKNOWN',destination:path.basename(filename),...(error.atomicRename||{})};
+      failure=error;
+      throw error;
+    }finally{
+      await file?.close().catch(()=>{});
+      // This unpredictable temporary is owned by this invocation. Never remove
+      // the destination to work around a Windows lock.
+      if(created)try{await removeFile(temporary,{force:true});}catch(error){if(failure)failure.atomicFile.cleanupCode=error.code||'UNKNOWN';else throw error;}
+    }
+  };
+}
+export const writeAtomicFile=createAtomicFileWriter();

package/runtime/cache-components-rsc.mjs

@@ -57,7 +57,9 @@ globalThis[codecSymbol] = {
       chunks.push(Buffer.from(value));
     }
     if (failure) throw failure;
-    return Buffer.concat(chunks, size);
+    // Each chunk above is already an owned copy. A single chunk needs no
+    // second allocation; never expose the producer's mutable stream storage.
+    return chunks.length===1?chunks[0]:Buffer.concat(chunks, size);
   },
   async decode(bytes, encoded, context) {
     return createFromReadableStream(new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); } }), {

package/runtime/dev-client.mjs

@@ -195,12 +195,17 @@ async function applyUpdate(message, {navigation=false}={}) {
     const route = kind === 'pages' ? manifest.pages.find(route => route.pattern === application.router.snapshot().pathname) : null;
     const entry = kind === 'pages' ? route?.client : manifest.app?.client;
     if (!entry) { reload('The current route changed. Page reloaded.'); return; }
-    if(!message.cssOnly)await import(/* webpackIgnore: true */ entry);
+    if(!message.cssOnly){
+      await import(/* webpackIgnore: true */ entry);
+      // Activated deferred modules must register their updated component
+      // families before Refresh runs, even when their loader is already cached.
+      await Promise.all((manifest.lazy||[]).map(module=>import(/* webpackIgnore: true */ module.url)));
+    }
     const pending = state.pending;
     if (pending) await application.devPrepare?.(pending.options);
     if (state.unsafe) { reload('An edited module exports values outside React components. Page reloaded.'); return; }
     if (kind === 'app' && application.devPrepareStyles) await application.devPrepareStyles(manifest.app.routes);
-    else await updateStyles(kind === 'pages' ? route.css : application.devStyles?.(manifest.app.routes) || manifest.app.css);
+    else await updateStyles([...(kind === 'pages' ? route.css : application.devStyles?.(manifest.app.routes) || manifest.app.css),...(manifest.lazy||[]).flatMap(module=>module.css)]);
     if (kind === 'app') application.devStylesApplied?.(manifest.app.routes, { commit: !!message.cssOnly || !pending });
     // An unrelated type-only edit may publish a new generation without changing
     // any browser module. Keep its existing runtime/hydration issues and current

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;
 }