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

package/runtime/dev-client.mjs

@@ -4,6 +4,7 @@ import { createConsoleCapture, isDevicePreview } from './dev-console.mjs';
 import { createDevToolsClient } from './dev-tools-client.mjs';
 import { createDevErrorOverlay } from './dev-error-overlay.mjs';
 import { collectDevIssues, formatDevIssuesForAI } from './dev-error-report.mjs';
+import { canSkipDevelopmentUpdate } from './dev-route-selection.mjs';
 
 const state = globalThis.__PRNEXT_DEV__ ||= {
   applications: new Map(), modules: new Map(), buildId: null, manifest: null,
@@ -154,9 +155,13 @@ function typeDiagnostics(errors) {
 }
 async function applyUpdate(message, {navigation=false}={}) {
   if(message.session&&state.session&&message.session!==state.session){reload('Development server restarted. Page reloaded.');return;}
-  if(message.sequence&&message.sequence<=(state.sequence||0))return;
+  if(message.sequence&&message.sequence<=(state.sequence||0)&&!(navigation&&state.skippedUpdate?.buildId===message.buildId))return;
   if (state.applying) {
     if(!state.queued||(message.sequence||0)>=(state.queued.sequence||0))state.queued={...message,navigation};
+    const active = state.refreshUpdate;
+    // Duplicate readiness messages must not cancel their own generation. The
+    // owner exists before any await, including before devCommit creates a GET.
+    if (active && message.buildId !== active.buildId && (message.sequence || 0) > active.sequence) active.abort.abort(new DOMException('Newer development generation', 'AbortError'));
     const pending=state.applied;await pending;
     if((message.sequence||0)>(state.sequence||0)&&state.applying)await state.applied;
     return;
@@ -174,7 +179,8 @@ async function applyUpdate(message, {navigation=false}={}) {
   const refreshStarted=performance.now();
   const localPath=location.pathname.slice((state.basePath||'').length)||'/';
   const affected=message.affectedRoutes;
-  if(state.confirmed&&affected&&!affected.some(pattern=>pattern.includes('[')||pattern===localPath||pattern+'/'===localPath)){
+  if(canSkipDevelopmentUpdate({confirmed:state.confirmed,navigation,ensuring:state.ensuring,affectedRoutes:affected,routes:message.routes,pathname:localPath})){
+    state.skippedUpdate={buildId:message.buildId};
     state.buildId=message.buildId;state.sequence=message.sequence;state.lastRefresh={buildId:message.buildId,durationMs:0,changed,skipped:true};
     document.documentElement.dataset.prnextDevBuild=message.buildId;
     if(hasCriticalIssue()&&state.issueKind==='build'){clearError();if(state.typeErrors)typeDiagnostics(state.typeErrors);}
@@ -183,28 +189,35 @@ async function applyUpdate(message, {navigation=false}={}) {
   }
   state.applying = true; state.confirmed=false; state.unsafe = false; state.refreshSourceChanged = false; state.pending = null; state.indicator?.update();
   let applied;state.applied=new Promise(resolve=>{applied=resolve;});
+  const update = { buildId: message.buildId, sequence: message.sequence || 0, abort: new AbortController() };
+  state.refreshUpdate = update;
   state.dismissedErrors = new WeakSet();
   state.dismissedDigests = new Set();
   try {
-    const response = await fetch(message.clientManifest, { cache: 'no-store', credentials: 'same-origin' });
+    const response = await fetch(message.clientManifest, { cache: 'no-store', credentials: 'same-origin', signal: update.abort.signal });
     if (!response.ok) throw new Error(`Development manifest failed (${response.status})`);
     const manifest = await response.json();
+    update.abort.signal.throwIfAborted();
     if (manifest.buildId !== message.buildId) throw new Error('Development build changed during refresh');
     const kind = state.currentKind;
     const application = await state.applications.get(kind);
+    update.abort.signal.throwIfAborted();
     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);
+      update.abort.signal.throwIfAborted();
       // 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)));
+      update.abort.signal.throwIfAborted();
     }
     const pending = state.pending;
     if (pending) await application.devPrepare?.(pending.options);
+    update.abort.signal.throwIfAborted();
     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);
+    if (kind === 'app' && application.devPrepareStyles) await application.devPrepareStyles(manifest.app.routes, update.abort.signal);
     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
@@ -216,19 +229,30 @@ async function applyUpdate(message, {navigation=false}={}) {
     }else if(hasCriticalIssue()&&(state.issueKind==='build'||errorKey(state.issue))){
       clearError();
     }
+    update.abort.signal.throwIfAborted();
+    if (!message.cssOnly && application.devBeforeRefresh?.({ navigation }) === false) return;
     if(!message.cssOnly)Refresh.performReactRefresh();
-    if (pending) await (navigation ? application.devSync?.(pending.options) : application.devCommit?.(pending.options));
+    if (pending) {
+      const committed = await (navigation ? application.devSync?.(pending.options) : application.devCommit?.(pending.options, { signal: update.abort.signal }));
+      // A private 'superseded' result replaces only the UI; its compiler
+      // generation is still applied. False remains a failed/aborted refresh.
+      if (committed === false || update.abort.signal.aborted) return;
+    }
     state.buildId = message.buildId;
     if(message.sequence)state.sequence=message.sequence;
     state.manifest = manifest;
+    state.skippedUpdate=undefined;
     document.documentElement.dataset.prnextDevBuild = message.buildId;
     state.lastRefresh={buildId:message.buildId,durationMs:Math.round(performance.now()-refreshStarted),changed};
-    await painted();state.confirmed=true;
+    await painted();
+    if (update.abort.signal.aborted) return;
+    state.confirmed=true;
     globalThis.dispatchEvent(new CustomEvent('prnext:refresh', { detail: state.lastRefresh }));
     globalThis.dispatchEvent(new CustomEvent('prnext:devtools:ready'));
     if(state.typeErrors)typeDiagnostics(state.typeErrors);
-  } catch (error) { showError(error); }
+  } catch (error) { if (!update.abort.signal.aborted) showError(error); }
   finally {
+    if (state.refreshUpdate === update) state.refreshUpdate = undefined;
     state.applying = false; state.pending = null; state.indicator?.update();
     applied();
     if (state.queued) { const queued = state.queued; state.queued = null; if (queued.buildId !== state.buildId) void applyUpdate(queued,{navigation:queued.navigation}); }
@@ -277,7 +301,7 @@ function connect(options) {
     const response=await fetch(`${options.basePath||''}/_prnext/ensure?client=${state.clientId}&path=${encodeURIComponent(url.pathname+url.search)}`,{cache:'no-store',credentials:'same-origin'});
     if(!response.ok)throw Error(await response.text());
     const update=await response.json();
-    if(update.buildId!==state.buildId)await applyUpdate(update,{navigation:true});
+    if(update.buildId!==state.buildId||state.skippedUpdate?.buildId===update.buildId)await applyUpdate(update,{navigation:true});
     }finally{state.ensuring--;}
   };
   const source = new EventSource(`${options.basePath || ''}/_prnext/dev?client=${state.clientId}&path=${encodeURIComponent(location.pathname+location.search)}`);

package/runtime/dev-compiler-broker.mjs

@@ -1,38 +1,35 @@
-import http from 'node:http';
-import {randomBytes,timingSafeEqual} from 'node:crypto';
+import {createServer} from 'node:net';
+import {randomBytes} from 'node:crypto';
 import {readFile,realpath} from 'node:fs/promises';
 import path from 'node:path';
+import {requestLoopback,serveLoopback} from './loopback-rpc.mjs';
 
 // Private control plane. Request headers and bodies never cross this endpoint.
 export async function createDevCompilerBroker({compile,maxPending=64}) {
-  const token=randomBytes(32).toString('base64url');let pending=0;
-  const server=http.createServer(async(req,res)=>{
-    const supplied=Buffer.from(req.headers.authorization||''),expected=Buffer.from('Bearer '+token);
-    if(req.method!=='POST'||req.url!=='/compile'||supplied.length!==expected.length||!timingSafeEqual(supplied,expected)){res.writeHead(403).end();return;}
-    if(pending>=maxPending){res.writeHead(503).end();return;}
-    pending++;
-    try{
-      const chunks=[];let bytes=0;
-      for await(const chunk of req){bytes+=chunk.length;if(bytes>65536)throw Error('Compiler request too large');chunks.push(chunk);}
-      // Decode once: an HTTP chunk boundary may split a UTF-8 route name.
-      const input=JSON.parse(Buffer.concat(chunks,bytes).toString('utf8'));if(typeof input.pattern!=='string'||!input.pattern.startsWith('/')||input.pattern.length>4096)throw Error('Invalid route pattern');
-      if(input.sources!==undefined&&(!Array.isArray(input.sources)||input.sources.length>32||!input.sources.every(p=>typeof p==='string'&&p.startsWith('/')&&p.length<=4096)))throw Error('Invalid retained route patterns');
-      const directory=await compile(input.pattern,input.sources||[]);
-      res.writeHead(200,{'content-type':'application/json','cache-control':'no-store'}).end(JSON.stringify({directory}));
-    }catch(error){res.writeHead(500,{'content-type':'application/json'}).end(JSON.stringify({error:String(error.message).slice(0,2048)}));}
-    finally{pending--;}
+  const token=randomBytes(32).toString('base64url'),sockets=new Set();let pending=0;
+  const server=createServer(socket=>{
+    sockets.add(socket);socket.once('close',()=>sockets.delete(socket));
+    serveLoopback(socket,{token,context:'development-compiler',timeout:120000,maxResponseBytes:65536,handle:async(input,admission)=>{
+      if(pending>=maxPending)throw Error('Development compiler is busy. Retry shortly.');
+      pending++;
+      try{
+        if(typeof input.pattern!=='string'||!input.pattern.startsWith('/')||input.pattern.length>4096)throw Error('Invalid route pattern');
+        if(input.sources!==undefined&&(!Array.isArray(input.sources)||input.sources.length>32||!input.sources.every(p=>typeof p==='string'&&p.startsWith('/')&&p.length<=4096)))throw Error('Invalid retained route patterns');
+        const directory=await compile(input.pattern,input.sources||[],admission);
+        return {directory};
+      }finally{pending--;}
+    }});
   });
-  server.requestTimeout=125000;server.headersTimeout=5000;
+  server.maxConnections=64;
   await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
-  return {descriptor:JSON.stringify({port:server.address().port,token}),close:()=>new Promise(resolve=>{server.close(resolve);server.closeIdleConnections();})};
+  return {descriptor:JSON.stringify({version:2,port:server.address().port,token}),close:()=>new Promise(resolve=>{server.close(resolve);for(const socket of sockets)socket.destroy();})};
 }
 
 export function deferredCompiler(descriptor,{root,home}) {
   const value=JSON.parse(descriptor);
-  if(!Number.isInteger(value.port)||value.port<1||value.port>65535||!/^[\w-]{43}$/.test(value.token))throw Error('Invalid private compiler endpoint');
+  if(value.version!==2||!Number.isInteger(value.port)||value.port<1||value.port>65535||!/^[\w-]{43}$/.test(value.token))throw Error('Invalid private compiler endpoint');
   return async(pattern,signal,sources=[])=>{
-    const response=await fetch(`http://127.0.0.1:${value.port}/compile`,{method:'POST',headers:{authorization:'Bearer '+value.token,'content-type':'application/json'},body:JSON.stringify({pattern,sources}),signal:AbortSignal.any([...(signal?[signal]:[]),AbortSignal.timeout(120000)])});
-    const result=await response.json();if(!response.ok)throw Error(result.error||'Deferred route compilation failed');
+    const result=await requestLoopback(value,{pattern,sources},{context:'development-compiler',signal,timeout:120000,maxResponseBytes:65536});
     const directory=await realpath(path.resolve(root,result.directory)),parent=await realpath(home),relative=path.relative(parent,directory);
     if(!relative||relative.startsWith('..')||path.isAbsolute(relative))throw Error('Compiler generation escaped its development session');
     const manifest=JSON.parse(await readFile(path.join(directory,'manifest.json'),'utf8'));

package/runtime/dev-gateway.mjs

@@ -1,9 +1,10 @@
 import {spawn} from 'node:child_process';
 
 export class DevGateway {
-  constructor(binary,root,{hostname,port,onEnsure,onOpen,onClose,onFatal}) {
-    this.next=0;this.pending=new Map();this.stopping=false;
-    this.child=spawn(binary,['dev-gateway',root,'--hostname',hostname,'--port',String(port)],{stdio:['pipe','pipe','inherit'],windowsHide:true});
+  constructor(binary,root,{hostname,port,onEnsure,onOpen,onClose,onFatal,onBeforeChild=()=>{},onChild=()=>{}},{spawnChild=spawn}={}) {
+    this.next=0;this.pending=new Map();this.ensures=new Map();this.stopping=false;
+    const ticket=onBeforeChild();
+    this.child=spawnChild(binary,['dev-gateway',root,'--hostname',hostname,'--port',String(port)],{stdio:['pipe','pipe','inherit'],windowsHide:true});onChild(this.child,ticket);
     this.closed=new Promise(resolve=>this.child.once('close',resolve));
     this.ready=new Promise((resolve,reject)=>{
       const timer=setTimeout(()=>{reject(Error('Development listener did not start'));this.child.kill();},15000);
@@ -16,18 +17,34 @@ export class DevGateway {
           if(message.type==='ready'){clearTimeout(timer);resolve(message);continue;}
           if(message.type==='open'){onOpen(message);continue;}
           if(message.type==='close'){onClose(message);continue;}
+          if(message.type==='ensure-cancel'){this.cancelEnsure(message.id);continue;}
           if(message.type==='ensure'){
-            Promise.resolve().then(()=>onEnsure(message.path,message.client)).then(value=>this.request('result',{request:message.id,value}),error=>this.request('result',{request:message.id,value:{error:String(error.message).slice(0,8000)}})).catch(error=>{if(!this.stopping)onFatal(error);});continue;
+            const now=Date.now();
+            if(!Number.isSafeInteger(message.id)||!Number.isSafeInteger(message.deadlineMs)||this.ensures.has(message.id)||this.ensures.size>=64){this.child.kill();continue;}
+            if(message.deadlineMs<=now)continue;
+            const deadlineMs=Math.min(message.deadlineMs,now+120000);
+            const controller=new AbortController(),entry={controller,timer:setTimeout(()=>this.cancelEnsure(message.id),deadlineMs-now)};
+            this.ensures.set(message.id,entry);
+            const reply=value=>{
+              if(this.ensures.get(message.id)!==entry)return;
+              clearTimeout(entry.timer);this.ensures.delete(message.id);
+              return this.request('result',{request:message.id,value});
+            };
+            Promise.resolve().then(()=>{
+              if(controller.signal.aborted)return;
+              return onEnsure(message.path,message.client,{signal:controller.signal,deadlineMs});
+            }).then(reply,error=>reply({error:String(error.message).slice(0,8000)})).catch(error=>{if(!this.stopping)onFatal(error);});continue;
           }
           const pending=this.pending.get(message.id);if(!pending)continue;
           this.pending.delete(message.id);clearTimeout(pending.timer);message.ok?pending.resolve(message.value):pending.reject(Error(message.error));
         }
       });
-      const failed=error=>{clearTimeout(timer);reject(error);for(const pending of this.pending.values()){clearTimeout(pending.timer);pending.reject(error);}this.pending.clear();if(!this.stopping)onFatal(error);};
+      const failed=error=>{clearTimeout(timer);reject(error);for(const id of this.ensures.keys())this.cancelEnsure(id);for(const pending of this.pending.values()){clearTimeout(pending.timer);pending.reject(error);}this.pending.clear();if(!this.stopping)onFatal(error);};
       this.child.once('error',failed);this.child.once('exit',(code,signal)=>failed(Error(`Development listener exited ${signal||code}`)));
     });
     this.child.stdin.on('error',()=>{});
   }
+  cancelEnsure(id){const entry=this.ensures.get(id);if(!entry)return;this.ensures.delete(id);clearTimeout(entry.timer);entry.controller.abort();}
   async request(command,values={}) {
     await this.ready;
     if(this.stopping||this.child.exitCode!==null)throw Error('Development listener is closed');
@@ -40,5 +57,5 @@ export class DevGateway {
       this.child.stdin.write(line);
     });
   }
-  async close(){this.stopping=true;this.child.stdin.end();const timer=setTimeout(()=>this.child.kill('SIGKILL'),6000);try{await this.closed;}finally{clearTimeout(timer);}}
+  async close(){this.stopping=true;for(const id of this.ensures.keys())this.cancelEnsure(id);this.child.stdin.end();const timer=setTimeout(()=>this.child.kill('SIGKILL'),6000);try{await this.closed;}finally{clearTimeout(timer);}}
 }

package/runtime/dev-route-selection.mjs

@@ -0,0 +1,64 @@
+const globalInput = /(?:^|\/)(?:package(?:-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|(?:tsconfig|jsconfig)\.json|(?:prnext|next|contentlayer|postcss|tailwind)\.config\.|\.env|(?:src\/)?(?:middleware|proxy)\.[^/]+$|pages\/_document\.|(?:global-error|global-not-found)\.)/;
+const generatedRouteFields = new Set(['module', 'client', 'css', 'cssScopes']);
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
+  return value;
+}
+const signature = value => JSON.stringify(stable(value));
+const routeContract = manifest => manifest.routes.map(route => Object.fromEntries(Object.entries(route).filter(([key]) => !generatedRouteFields.has(key)))).sort((a, b) => a.id.localeCompare(b.id));
+function actionContract(manifest) {
+  const ids = Object.keys(manifest.app?.actions || {}).sort();
+  if (!ids.length) return [];
+  const metadata = manifest.devActions;
+  if (metadata?.version !== 1 || metadata.complete !== true || manifest.devDependencyStatus?.complete !== true || !Array.isArray(metadata.actions)) return;
+  const modules = new Set((manifest.devModules || []).map(record => record.route));
+  const routed = new Set((manifest.devDependencies || []).flatMap(record => record.files));
+  if (signature(metadata.actions.map(action => action.id).sort()) !== signature(ids)) return;
+  const owners = new Set();
+  for (const action of metadata.actions) {
+    const owner = action.file + '\0' + action.binding;
+    if (!modules.has(action.file) || !routed.has(action.file) || owners.has(owner) || !Array.isArray(action.runtimes)) return;
+    owners.add(owner);
+  }
+  return [...metadata.actions].sort((a, b) => (a.file + '\0' + a.binding).localeCompare(b.file + '\0' + b.binding));
+}
+
+// Both committed graphs participate: removed imports belong to the old graph,
+// newly introduced imports to the new one. No partial/unknown graph is proof.
+export function selectiveDevelopmentRoutes(previous, next, { changed, affectedRoutes, affectedModules = [], nextAffected } = {}) {
+  if (!previous || !changed?.length || !Array.isArray(affectedRoutes) || !nextAffected || nextAffected.complete !== true || !Array.isArray(nextAffected.unknown) || nextAffected.unknown.length || !Array.isArray(nextAffected.routes) ||
+      previous.devDependencyStatus?.complete === false || next.devDependencyStatus?.complete === false || changed.some(file => globalInput.test(file))) return;
+  // The visible URL is not proof of the rendered route under server rewrites,
+  // localized routing, or intercepted/parallel branches. Keep these global
+  // until the browser can certify every visible route identity.
+  for (const manifest of [previous, next]) if (manifest.middleware || manifest.config?.i18n ||
+      Object.values(manifest.customRoutes?.rewrites || {}).some(rules => rules.length) ||
+      manifest.routes.some(route => route.parallel || route.interception)) return;
+  if (signature([previous.config, previous.customRoutes, routeContract(previous)]) !== signature([next.config, next.customRoutes, routeContract(next)])) return;
+  const before = actionContract(previous), after = actionContract(next);
+  if (!before || !after || previous.app?.actionKey !== next.app?.actionKey ||
+      signature(before.map(({id, ...action}) => action)) !== signature(after.map(({id, ...action}) => action))) return;
+  const modules = new Set([...affectedModules, ...(nextAffected.modules || [])]);
+  for (let i = 0; i < before.length; i++) if (before[i].id !== after[i].id && !modules.has(before[i].file)) return;
+  const routes = [...new Set([...affectedRoutes, ...nextAffected.routes])].sort();
+  return Buffer.byteLength(JSON.stringify(routes)) <= 32 * 1024 ? routes : undefined;
+}
+
+// An ensure/navigation transaction must prepare the new loader even when its
+// destination differs from location.pathname until history is committed.
+export function canSkipDevelopmentUpdate({ confirmed, navigation, ensuring, affectedRoutes, routes, pathname }) {
+  if (!confirmed || navigation || ensuring || !Array.isArray(affectedRoutes) || !Array.isArray(routes)) return false;
+  let parts; try { parts = pathname.split('/').filter(Boolean).map(decodeURIComponent); } catch { return false; }
+  const matches = pattern => {
+    const segments = pattern.split('/').filter(Boolean); let index = 0;
+    for (const segment of segments) {
+      if (/^\[\[\.\.\.[^\]]+\]\]$/.test(segment)) return true;
+      if (/^\[\.\.\.[^\]]+\]$/.test(segment)) return index < parts.length;
+      if (index >= parts.length || !(segment.startsWith('[') && segment.endsWith(']')) && segment !== parts[index]) return false;
+      index++;
+    }
+    return index === parts.length;
+  };
+  return routes.some(matches) && !affectedRoutes.some(matches);
+}

package/runtime/dev-runtime-pool.mjs

@@ -5,11 +5,12 @@ import {fileURLToPath} from 'node:url';
 import path from 'node:path';
 import {EventEmitter} from 'node:events';
 
-export function createDevRuntimePool({binary,root,home,environment={},onChild=()=>{}}){
+export function createDevRuntimePool({binary,root,home,environment={},onBeforeChild=()=>{},onChild=()=>{},onReady=()=>{}}){
   let spare,disposed=false;const children=new Set();
   function create(){
     if(disposed)throw Error('Development runtime is closed');
     const token=randomBytes(32).toString('base64url');
+    const ticket=onBeforeChild();
     const child=spawn(binary,['dev-spare',root,'--node',process.execPath,'--script',fileURLToPath(new URL('./dev-runtime-spare.mjs',import.meta.url))],{cwd:root,windowsHide:true,stdio:['pipe','pipe','pipe'],env:{...process.env,...environment,NODE_ENV:'development',PRNEXT_DEV_SPARE_TOKEN:token}});
     children.add(child);onChild(child);
     const messages=new EventEmitter();let buffer='';child.stdout.setEncoding('utf8');child.stdout.on('data',chunk=>{buffer+=chunk;if(buffer.length>65536){child.kill();return;}for(let end;(end=buffer.indexOf('\n'))>=0;){const line=buffer.slice(0,end);buffer=buffer.slice(end+1);try{const message=JSON.parse(line);if(message.type)messages.emit(message.type,message);}catch{}}});
@@ -22,7 +23,7 @@ export function createDevRuntimePool({binary,root,home,environment={},onChild=()
       const message=value=>{clean();resolve(value);};
       messages.on(type,message);child.once('exit',exit);child.once('error',fail);
     });
-    const ready=wait('warm');ready.catch(()=>{if(spare?.child===child)spare=undefined;void stop(child);});
+    const ready=wait('warm').then(info=>{onReady(child,info,ticket);return info;});ready.catch(()=>{if(spare?.child===child)spare=undefined;void stop(child);});
     return {child,token,ready,wait};
   }
   async function stop(child){

package/runtime/dev-runtime-spare.mjs

@@ -48,7 +48,7 @@ const broker=net.createServer(socket=>{
   socket.on('close',()=>{const owned=controls.delete(socket);if(owned&&!controls.size&&ready)process.stdin.emit('end');});
 });
 broker.maxConnections=16;
-broker.listen(0,'127.0.0.1',()=>{broker.unref();announce({type:'warm',port:broker.address().port});});
+broker.listen(0,'127.0.0.1',()=>{broker.unref();announce({type:'warm',port:broker.address().port,pid:process.pid});});
 let control='';const arm=chunk=>{control+=chunk;if(control.length>8192)process.exit(1);if(!control.includes('\n'))return;process.stdin.off('data',arm);
   let message;try{message=JSON.parse(control.trim());}catch{process.exit(1);}if(message?.type!=='arm'||armed)process.exit(1);
   void realpath(message.dist).then(dist=>{if(!dist.startsWith(root+path.sep))throw Error('Generation outside project');armed={dist};announce({type:'armed'});}).catch(()=>process.exit(1));

package/runtime/dev-session-retention.mjs

@@ -0,0 +1,154 @@
+import {randomUUID} from 'node:crypto';
+import {hostname} from 'node:os';
+import {constants, writeFileSync, renameSync, rmSync} from 'node:fs';
+import {lstat, open, opendir, rm} from 'node:fs/promises';
+import path from 'node:path';
+import {captureStorageDirectory,verifyStorageDirectories,sameStoragePath} from './storage-path.mjs';
+
+const marker = '.owner.json', disabledMarker = '.recovery-disabled', uuid = /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/;
+const grace = 60_000, maxChildren = 4096, maxMarker = 64 * 1024;
+const alive = pid => {try {process.kill(pid, 0); return true;} catch (error) {return error.code !== 'ESRCH';}};
+const pid = value => Number.isSafeInteger(value) && value > 0;
+
+/** A ticket is durable before a spawn. An interrupted spawn/metadata update
+ * leaves the session ineligible for automatic recovery, never falsely idle. */
+export function createDevelopmentSessionOwner(home, {session, processId = process.pid, host = hostname(), now = Date.now, warn = console.warn} = {}) {
+  if (!uuid.test(session) || path.basename(home) !== session || !pid(processId)) throw Error('Invalid development session owner');
+  const state = {version: 1, session, token: randomUUID(), pid: processId, host, createdAt: now(), updatedAt: now(), eligible: true, children: [], pending: []};
+  function publish(initial = false) {
+    state.updatedAt = now();
+    const text = JSON.stringify(state) + '\n';
+    if (Buffer.byteLength(text) > maxMarker) throw Error('Development owner metadata exceeds its budget');
+    const file = path.join(home, marker);
+    if (initial) {writeFileSync(file, text, {flag: 'wx', mode: 0o600}); return;}
+    const temporary = file + '.' + randomUUID() + '.tmp';
+    try {writeFileSync(temporary, text, {flag: 'wx', mode: 0o600}); renameSync(temporary, file);}
+    finally {rmSync(temporary, {force: true});}
+  }
+  publish(true);
+  function disable() {
+    // A separate create-only marker also works if Windows has temporarily
+    // locked the owner receipt. A spawn may proceed only once this safeguard
+    // or its pending ticket is durable.
+    try {writeFileSync(path.join(home, disabledMarker), 'Incomplete development child ownership.\n', {flag: 'wx', mode: 0o600});}
+    catch (error) {if (error.code !== 'EEXIST') throw error;}
+    state.eligible = false; try {publish();} catch { /* The create-only marker forbids cleanup. */ }
+  }
+  return {
+    beforeSpawn() {
+      if (!state.eligible) return null;
+      if (state.pending.length >= 128 || state.children.length >= maxChildren) {disable(); return null;}
+      const ticket = randomUUID(); state.pending.push(ticket); try {publish();} catch {disable();} return ticket;
+    },
+    spawned(ticket, child, descendants = []) {
+      if (!state.eligible) return;
+      if (!state.pending.includes(ticket)) {disable(); return;}
+      if (!pid(child?.pid) || descendants.some(value => !pid(value))) {state.eligible = false; try {disable();} catch { /* The pre-spawn ticket remains durable. */ } return;}
+      for (const value of [child.pid, ...descendants]) if (!state.children.includes(value)) state.children.push(value);
+      state.pending = state.pending.filter(value => value !== ticket);
+      try {publish();} catch (error) {state.eligible = false; try {disable();} catch { /* The pre-spawn ticket remains durable. */ } warn('Development session recovery disabled: ' + (error.code || 'metadata publication failed'));}
+    },
+    disable,
+  };
+}
+
+async function readOwner(home) {
+  const name = path.join(home, marker), info = await lstat(name);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > maxMarker) return;
+  const file = await open(name, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const bytes = Buffer.alloc(maxMarker + 1), {bytesRead} = await file.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > maxMarker) return;
+    const text = bytes.toString('utf8', 0, bytesRead), value = JSON.parse(text);
+    if (value.version !== 1 || value.session !== path.basename(home) || !uuid.test(value.session) || !uuid.test(value.token) || !pid(value.pid) || typeof value.host !== 'string' || value.host.length > 255 || !Number.isSafeInteger(value.createdAt) || !Number.isSafeInteger(value.updatedAt) || value.updatedAt < value.createdAt || value.eligible !== true || !Array.isArray(value.pending) || value.pending.length || !Array.isArray(value.children) || value.children.length > maxChildren || value.children.some(value => !pid(value))) return;
+    return {value, text};
+  } finally {await file.close();}
+}
+
+async function ordinaryTree(home, budget, snapshots) {
+  const directory = await captureStorageDirectory(home);
+  if (!directory) return false;
+  snapshots.push(directory);
+  for await (const entry of await opendir(home)) {
+    if (++budget.files > 32_768) return false;
+    const file = path.join(home, entry.name), info = await lstat(file);
+    if (info.isSymbolicLink()) return false;
+    if (info.isDirectory()) {if (!await ordinaryTree(file, budget, snapshots)) return false;}
+    else if (!info.isFile() || (budget.bytes += info.size) > 2 * 1024 ** 3) return false;
+  }
+  return true;
+}
+
+/** Called while the project's exclusive development lock is held. Legacy,
+ * foreign, active, ambiguous and unmarked sessions are always preserved. */
+export async function pruneDevelopmentSessions(root, {host = hostname(), now = Date.now(), isAlive = alive, graceMs = grace, remove = rm} = {}) {
+  const report = {removed: 0, retained: 0, failed: 0};
+  // The caller already holds the canonical project's development lock. Do not
+  // recanonicalize a replaced root into a different project's storage.
+  root = path.resolve(root);
+  const container = path.join(root, '.prnext-dev');
+  let info;
+  try {info = await lstat(container);} catch (error) {if (error.code === 'ENOENT') return report; throw error;}
+  if (!info.isDirectory() || info.isSymbolicLink()) return report;
+  const ancestors = [await captureStorageDirectory(root), await captureStorageDirectory(container)];
+  if (!await verifyStorageDirectories(ancestors)) return report;
+  let scanned = 0;
+  for await (const entry of await opendir(container)) {
+    if (++scanned > 256) break;
+    if (!entry.isDirectory() || !uuid.test(entry.name)) {report.retained++; continue;}
+    const home = path.join(container, entry.name);
+    try {
+      const snapshots = [...ancestors, await captureStorageDirectory(home)];
+      if (!await verifyStorageDirectories(snapshots)) {report.retained++; continue;}
+      const owner = await readOwner(home);
+      if (await lstat(path.join(home, disabledMarker)).then(() => true, error => {if (error.code === 'ENOENT') return false; throw error;})) {report.retained++; continue;}
+      const inactive = value => value.host === host && value.updatedAt <= now - graceMs && value.createdAt <= now && ![value.pid, ...value.children].some(isAlive);
+      if (!owner || !inactive(owner.value) || !await verifyStorageDirectories(snapshots) || !await ordinaryTree(home, {files: 0, bytes: 0}, snapshots) || !await verifyStorageDirectories(snapshots)) {report.retained++; continue;}
+      // Validate the same marker and lifetime after the bounded tree walk. A
+      // currently running session can never be deleted merely because it is old.
+      const current = await readOwner(home), directory = await lstat(home);
+      const disabled = await lstat(path.join(home, disabledMarker)).then(() => true, error => {if (error.code === 'ENOENT') return false; throw error;});
+      if (disabled || !current || current.text !== owner.text || !inactive(current.value) || !directory.isDirectory() || directory.isSymbolicLink() || !await verifyStorageDirectories(snapshots)) {report.retained++; continue;}
+      await remove(home, {recursive: true, force: true, maxRetries: 3, retryDelay: 100}); report.removed++;
+    } catch {report.failed++;}
+  }
+  return report;
+}
+
+/** Failed generation cleanup remains in this retryable queue, including the
+ * exact completed phase. Nothing is deleted before requests have drained. */
+export function createRetiredGenerationCleanup({root, home, gateway, stop, remove = rm, warn = console.warn}) {
+  const pending = new Map(); let running;
+  const ownedHome = path.resolve(home);
+  const ancestry = directory => [path.resolve(root), path.join(path.resolve(root), '.prnext-dev'), ownedHome, directory];
+  async function storage(item, directory) {
+    item.snapshots ??= await Promise.all(ancestry(directory).map(captureStorageDirectory));
+    return verifyStorageDirectories(item.snapshots);
+  }
+  async function clean(item) {
+    const directory = path.resolve(root, item.generation.directory);
+    if (!sameStoragePath(path.dirname(directory), ownedHome) || !uuid.test(path.basename(directory)) || item.generation.id !== path.basename(directory)) throw Error('Invalid retired development generation');
+    if (!await storage(item, directory)) throw Error('Development generation storage changed');
+    if (item.phase === 0) {await gateway.request('retire', {generation: item.generation.id}); item.phase++;}
+    if (!await storage(item, directory)) throw Error('Development generation storage changed');
+    if (item.phase === 1) {await item.generation.runtime?.close(); item.phase++;}
+    if (item.phase === 2) {await stop(item.generation.child); item.phase++;}
+    if (item.phase === 3) {await gateway.request('forget', {generation: item.generation.id}); item.phase++;}
+    const snapshots = [...item.snapshots];
+    if (!await storage(item, directory) || !await ordinaryTree(directory, {files: 0, bytes: 0}, snapshots) || !await verifyStorageDirectories(snapshots)) throw Error('Development generation storage changed');
+    await remove(directory, {recursive: true, force: true, maxRetries: 10, retryDelay: 100});
+  }
+  const retry = () => {
+    if (running) return running;
+    running = (async () => {
+      for (const [id, item] of [...pending]) {
+        try {await clean(item); pending.delete(id);}
+        catch (error) {warn('Development generation cleanup: ' + error.message);}
+      }
+    })().finally(() => {running = undefined;});
+    return running;
+  };
+  return {get pending() {return pending.size;}, enqueue(generation) {if (!pending.has(generation.id)) pending.set(generation.id, {generation, phase: 0}); return retry();}, retry,
+    async close() {await running; for (const item of pending.values()) {const directory=path.resolve(root,item.generation.directory);if(await storage(item,directory))await item.generation.runtime?.close();else await stop(item.generation.runtime?.child);await stop(item.generation.child);}},
+  };
+}

package/runtime/development-flight.mjs

@@ -0,0 +1,59 @@
+// Only owned development navigation GETs opt into a partial Flight decoder. An intentional
+// supersession closes that decoder while cancelling its sole upstream reader;
+// genuine transport errors still reject. This stream never claims genuine EOF
+// on behalf of the transport or retains response bytes as a reusable delta base.
+export function supersedableDevelopmentFlight(source, signal) {
+  const reader = source.getReader();
+  let controller, closed = false;
+  const clean = () => {
+    signal.removeEventListener('abort', abort);
+    try { reader.releaseLock(); } catch {}
+  };
+  const cancel = reason => Promise.resolve(reader.cancel(reason)).catch(() => {}).finally(clean);
+  const abort = () => {
+    if (closed) return;
+    closed = true;
+    controller.close();
+    void cancel(signal.reason);
+  };
+  return new ReadableStream({
+    start(value) {
+      controller = value;
+      signal.addEventListener('abort', abort, { once: true });
+      if (signal.aborted) abort();
+    },
+    async pull(value) {
+      if (closed) return;
+      try {
+        const next = await reader.read();
+        if (closed) return;
+        // React's ordinary EOF rejects missing rows. With partial decoding
+        // enabled, reserve a clean close exclusively for owned supersession.
+        if (next.done) { closed = true; clean(); value.error(new Error('Connection closed.')); }
+        else value.enqueue(next.value);
+      } catch (error) {
+        if (closed) return;
+        closed = true;
+        value.error(error);
+        await cancel(error);
+      }
+    },
+    async cancel(reason) {
+      if (closed) return;
+      closed = true;
+      await cancel(reason);
+    },
+  }, { highWaterMark: 0 });
+}
+
+// A partial decoder also halts an unresolved root on supersession. Race its
+// root promise explicitly so cancellation cannot leave navigation waiting on it.
+export function developmentFlightRoot(root, signal) {
+  return new Promise((resolve, reject) => {
+    const clean = () => signal.removeEventListener('abort', abort);
+    const abort = () => { clean(); reject(signal.reason || new DOMException('Development refresh cancelled', 'AbortError')); };
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve(root).then(value => { clean(); resolve(value); }, error => { clean(); reject(error); });
+    if (signal.aborted) abort();
+  });
+}

package/runtime/development-queue.mjs

@@ -0,0 +1,33 @@
+// Cancellation owns only a queued request. An executing build can also serve
+// another navigation or a watcher update, and must finish normally.
+export function createDevelopmentQueue({isStopping=()=>false,now=Date.now}={}) {
+  const waiting=[];let running=false;const idle=[];
+  const expired=()=>Error('Development request expired before compilation started');
+  function drain(){
+    if(running)return;
+    const entry=waiting.shift();
+    if(!entry){for(const resolve of idle.splice(0))resolve();return;}
+    entry.clean();running=true;
+    Promise.resolve().then(()=>{
+      if(isStopping())throw Error('Development is stopping');
+      if(entry.signal?.aborted||entry.deadlineMs!==undefined&&now()>=entry.deadlineMs)throw expired();
+      return entry.run();
+    }).then(entry.resolve,entry.reject).finally(()=>{running=false;drain();});
+  }
+  return {
+    enqueue(run,{signal,deadlineMs}={}) {
+      if(signal?.aborted||deadlineMs!==undefined&&(!Number.isSafeInteger(deadlineMs)||now()>=deadlineMs))return Promise.reject(expired());
+      return new Promise((resolve,reject)=>{
+        let timer;
+        const cancel=()=>{const index=waiting.indexOf(entry);if(index<0)return;waiting.splice(index,1);entry.clean();reject(expired());if(!running)drain();};
+        const entry={run,resolve,reject,signal,deadlineMs,clean(){clearTimeout(timer);signal?.removeEventListener('abort',cancel);}};
+        waiting.push(entry);signal?.addEventListener('abort',cancel,{once:true});
+        if(deadlineMs!==undefined)timer=setTimeout(cancel,Math.max(0,deadlineMs-now()));
+        // Defer the first start so same-turn cancellation cannot start work.
+        queueMicrotask(drain);
+      });
+    },
+    idle(){return running||waiting.length?new Promise(resolve=>idle.push(resolve)):Promise.resolve();},
+    get pending(){return waiting.length;},
+  };
+}