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

package/runtime/cache-result.mjs

@@ -0,0 +1,58 @@
+// Private, versioned cache bytes. These packets never become browser Flight.
+import {isUtf8} from 'node:buffer';
+const MAGIC=Buffer.from([0x50,0x52,0x4e,0x43,2]);
+const HEADER=MAGIC.length+1;
+export const CACHE_RESULT_LIMIT=16*1024*1024;
+export const CACHE_RESULT_KEY_VERSION='flight-primitives-v2';
+const SCALAR_LIMIT=CACHE_RESULT_LIMIT-64*1024;
+function packet(type,payload=Buffer.alloc(0)){
+  if(payload.length>CACHE_RESULT_LIMIT)throw new Error('Cached React result exceeds the 16 MiB rendering limit');
+  const bytes=Buffer.allocUnsafe(HEADER+payload.length);MAGIC.copy(bytes);bytes[MAGIC.length]=type;payload.copy(bytes,HEADER);return bytes;
+}
+function textPacket(type,value,length){
+  const bytes=Buffer.allocUnsafe(HEADER+length);MAGIC.copy(bytes);bytes[MAGIC.length]=type;bytes.write(value,HEADER,length,'utf8');return bytes;
+}
+export function primitiveCacheResult(value){
+  if(value===null)return packet(1);
+  switch(typeof value){
+    case 'undefined':return packet(2);
+    case 'boolean':return packet(value?3:4);
+    case 'number':{const bytes=Buffer.allocUnsafe(8);bytes.writeDoubleLE(value);return packet(5,bytes);}
+    case 'bigint':{const text=String(value);return text.length>SCALAR_LIMIT?undefined:textPacket(6,text,text.length);}
+    case 'string':{
+      // Leave framing-sensitive boundary values to the official Flight limit.
+      if(value.length>SCALAR_LIMIT)return undefined;
+      // Flight's small JSON strings and large UTF8 text rows do not normalize
+      // lone surrogates or BOMs alike. Keep any such string on the fallback,
+      // independently of React's text-row threshold or chunk boundaries.
+      if(!value.isWellFormed()||value.includes('\ufeff'))return undefined;
+      const length=Buffer.byteLength(value);
+      if(length>SCALAR_LIMIT)return undefined;
+      return textPacket(7,value,length);
+    }
+    // In particular, do not enumerate objects, inspect then, or read a proxy or
+    // getter. React owns every nonprimitive result and its temporary references.
+    default:return undefined;
+  }
+}
+export function flightCacheResult(chunks,size){
+  if(size>CACHE_RESULT_LIMIT)throw new Error('Cached React result exceeds the 16 MiB rendering limit');
+  // Ordinary Flight keeps its original bytes and sole aggregate copy. Reserve
+  // the whole first-byte family for this private protocol, without assuming
+  // anything about React's current or future row syntax. Inspect the aggregate
+  // so an empty leading chunk cannot hide a reserved first byte.
+  const bytes=Buffer.concat(chunks,size);
+  return isCacheResultPacket(bytes)?packet(0,bytes):bytes;
+}
+export function isCacheResultPacket(bytes){return bytes[0]===MAGIC[0];}
+export function readCacheResult(bytes){
+  if(!Buffer.isBuffer(bytes)||bytes.length<HEADER||bytes.length>HEADER+CACHE_RESULT_LIMIT||!bytes.subarray(0,MAGIC.length).equals(MAGIC))throw new Error('Invalid RSC cache result envelope');
+  const type=bytes[MAGIC.length],payload=bytes.subarray(HEADER);
+  // Unwrap an escaped raw payload once; never interpret it as another packet.
+  if(type===0&&isCacheResultPacket(payload))return {flight:payload};
+  if(type>=1&&type<=4&&payload.length===0)return {value:type===1?null:type===2?undefined:type===3};
+  if(type===5&&payload.length===8)return {value:payload.readDoubleLE()};
+  if(type===6&&payload.length&&/^(?:0|-?[1-9]\d*)$/.test(payload.toString()))return {value:BigInt(payload.toString())};
+  if(type===7&&isUtf8(payload))return {value:payload.toString()};
+  throw new Error('Invalid RSC cache result envelope');
+}

package/runtime/dev-client.mjs

@@ -158,6 +158,10 @@ async function applyUpdate(message, {navigation=false}={}) {
   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;
@@ -185,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
@@ -218,20 +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}); }

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,10 +1,10 @@
 import {spawn} from 'node:child_process';
 
 export class DevGateway {
-  constructor(binary,root,{hostname,port,onEnsure,onOpen,onClose,onFatal,onBeforeChild=()=>{},onChild=()=>{}}) {
-    this.next=0;this.pending=new Map();this.stopping=false;
+  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=spawn(binary,['dev-gateway',root,'--hostname',hostname,'--port',String(port)],{stdio:['pipe','pipe','inherit'],windowsHide:true});onChild(this.child,ticket);
+    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);
@@ -17,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');
@@ -41,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/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;},
+  };
+}

package/runtime/development.mjs

@@ -25,6 +25,7 @@ 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 {createDevelopmentQueue} from './development-queue.mjs';
 import {pruneDevelopmentStyles} from './dev-style-retention.mjs';
 import {createDevelopmentSessionOwner,pruneDevelopmentSessions,createRetiredGenerationCleanup} from './dev-session-retention.mjs';
 
@@ -107,12 +108,13 @@ async function runDevelopment(projectRoot,args,binary) {
   let compiler,gateway,watcher,timer,tools,hostRelay,hostRelayTask,stopping=false,current,discovery,typeChecker,readyState={state:'building'},typeErrors=[],sequence=0;
   let dependencyIndexValid=false;
   const lifecycle=new AbortController();
-  let queue=Promise.resolve(),stateQueue=Promise.resolve(),output='.prnext',changes=new Set(),active=new Map(),failed=new Set();
+  const compilationQueue=createDevelopmentQueue({isStopping:()=>stopping});
+  let stateQueue=Promise.resolve(),output='.prnext',changes=new Set(),active=new Map(),failed=new Set();
   const failedPaths=new Set();
   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 retiredCleanup=createRetiredGenerationCleanup({root,home,gateway:{request:(...args)=>gateway.request(...args)},stop});
-  const compilerBroker=await createDevCompilerBroker({compile:(pattern,sources)=>serialized(async()=>{
+  const compilerBroker=await createDevCompilerBroker({compile:(pattern,sources,admission)=>serialized(async()=>{
     if(stopping)throw Error('Development is stopping');
     if(!discovery)await discover();
     const patterns=[...new Set([pattern,...sources])];
@@ -121,7 +123,7 @@ async function runDevelopment(projectRoot,args,binary) {
     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;
-  })});
+  },admission)});
   const runtimePool=createDevRuntimePool({binary,root,home,environment:{PRNEXT_DEV_COMPILER:compilerBroker.descriptor,PRNEXT_INSPECT_DIR:diagnosticsDirectory,...(options.profile?{PRNEXT_PROFILE:options.profile}:{})},onBeforeChild:()=>sessionOwner.beforeSpawn(),onReady:(child,info,ticket)=>sessionOwner.spawned(ticket,child,[info.pid]),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)})),
@@ -159,7 +161,7 @@ async function runDevelopment(projectRoot,args,binary) {
     });
     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;};
+  const serialized=(run,admission)=>compilationQueue.enqueue(run,admission);
   async function compilerRequest(type,values={}){
     if(!compiler||compiler.exitCode!==null||compiler.signalCode){
       const cache=await privateCacheDirectory(root,'dev-compiler-v8');
@@ -277,7 +279,7 @@ async function runDevelopment(projectRoot,args,binary) {
     }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,exact=false){
+  async function ensure(raw,client,exact=false,admission={}){
     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');
@@ -289,7 +291,7 @@ async function runDevelopment(projectRoot,args,binary) {
       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};
-    });
+    },admission);
     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)){
@@ -315,7 +317,7 @@ async function runDevelopment(projectRoot,args,binary) {
       try{await rebuild([...active.keys()]);}catch(error){if(route){failed.add(route.pattern);active.delete(route.pattern);}throw error;}
     }
     return updateInfo();
-  });}
+  },admission);}
   async function changed(){
     try{
     const pending=[...changes];changes.clear();
@@ -349,7 +351,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,retiredCleanup.close()]);
-      await queue.catch(()=>{});await compilerBroker.close();await stateQueue;await rm(home,{recursive:true,force:true,maxRetries:10,retryDelay:100});await rm(stateFile,{force:true});
+      await compilationQueue.idle();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();}};
@@ -363,7 +365,7 @@ async function runDevelopment(projectRoot,args,binary) {
       return {...updateInfo(),...result};
     })});
     await writeState({state:'building',session});
-    gateway=new DevGateway(binary,root,{...options,onEnsure:ensure,onFatal:fatal,onBeforeChild:()=>sessionOwner.beforeSpawn(),onChild:(child,ticket)=>sessionOwner.spawned(ticket,child),
+    gateway=new DevGateway(binary,root,{...options,onEnsure:(raw,client,admission)=>ensure(raw,client,false,admission),onFatal:fatal,onBeforeChild:()=>sessionOwner.beforeSpawn(),onChild:(child,ticket)=>sessionOwner.spawned(ticket,child),
       onOpen:message=>{const route=discovery&&findRoute(message.path);if(route)pins.set(message.client,{pattern:route.pattern,connection:message.connection});},
       onClose:message=>{if(pins.get(message.client)?.connection===message.connection)pins.delete(message.client);}});
     const listener=await gateway.ready;

package/runtime/flight-diagnostics.mjs

@@ -0,0 +1,48 @@
+import diagnostics from '../compat/diagnostics.cjs';
+
+const phases = new Set(['ssr', 'rsc']);
+const outcomes = new Set(['completed', 'failed', 'cancelled', 'timedOut']);
+const count = value => Number.isSafeInteger(value) && value >= 0 ? Math.min(value, 32 * 1024 * 1024) : 0;
+
+// Disabled in the ordinary request path. No body, URL, parameters, nonce, model,
+// client references or request context is retained, even when enabled. Timings
+// include asynchronous rendering/waiting; they are NOT isolated encoder CPU.
+export function createFlightMeasurement(request, phase, options) {
+  if (!(options?.enabled ?? diagnostics.enabled) || !phases.has(phase)) return;
+  const now = options?.now ?? (() => performance.now());
+  const record = options?.record ?? diagnostics.record;
+  const started = now();
+  const route = typeof request?.routePattern === 'string' ? request.routePattern.slice(0, 256) : '<unattributed>';
+  const method = /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(request?.method) ? request.method : '_OTHER';
+  let ended = false, firstChunkMs, modelReadyMs, shellReadyMs, ppr;
+  const elapsed = () => Math.max(0, Math.min(86400000, now() - started));
+  const metrics = {
+    flightBytes: 0, flightChunks: 0, responseBytes: 0, peakQueuedBytes: 0,
+    chunk(bytes) {
+      if (ended) return;
+      firstChunkMs ??= elapsed();
+      metrics.flightBytes += count(bytes);
+      metrics.flightChunks++;
+    },
+    mark(name) {
+      if (ended) return;
+      if (name === 'modelReady') modelReadyMs ??= elapsed();
+      else if (name === 'shellReady') shellReadyMs ??= elapsed();
+    },
+    partial(mode) { if (!ended && ['direct', 'normalized'].includes(mode)) ppr = mode; },
+    finish(outcome, status) {
+      if (ended || !outcomes.has(outcome)) return;
+      ended = true;
+      const event = { route, method, phase, outcome, durationMs: elapsed(),
+        flightBytes: count(metrics.flightBytes), flightChunks: count(metrics.flightChunks),
+        responseBytes: count(metrics.responseBytes), peakQueuedBytes: count(metrics.peakQueuedBytes),
+        ...(Number.isInteger(status) && status >= 100 && status <= 599 ? {status} : {}),
+        ...(firstChunkMs !== undefined ? {firstChunkMs} : {}),
+        ...(modelReadyMs !== undefined ? {modelReadyMs} : {}),
+        ...(shellReadyMs !== undefined ? {shellReadyMs} : {}), ...(ppr ? {ppr} : {}) };
+      // Diagnostics must never replace a response/error with an export failure.
+      try { record('flight', event); } catch {}
+    },
+  };
+  return metrics;
+}

package/runtime/flight-tap.mjs

@@ -1,7 +1,7 @@
 // Share Flight allocations with the SSR decoder, then group only already
 // available bootstrap bytes. Never wait for a future Suspense chunk to fill a
 // block. The queue's pre-shell ceiling remains the overall response budget.
-export function flightTap(source) {
+export function flightTap(source, metrics) {
   const reader=source.getReader(),queue=[];
   let head=0,bytes=0,done=false,failure,outputStarted=false,wakeData,wakeSpace,cancelled;
   const finish=error=>{done=true;failure=error;wakeData?.();wakeData=undefined;wakeSpace?.();wakeSpace=undefined;};
@@ -11,17 +11,22 @@ export function flightTap(source) {
       while(!done&&outputStarted&&bytes>=128*1024)await new Promise(resolve=>{wakeSpace=resolve;});
       if(done){if(failure)controller.error(failure);else controller.close();return;}
       const next=await reader.read();if(next.done){finish();controller.close();return;}
-      queue.push(next.value);bytes+=next.value.byteLength;wakeData?.();wakeData=undefined;controller.enqueue(next.value);
+      queue.push(next.value);bytes+=next.value.byteLength;
+      if(metrics){metrics.chunk(next.value.byteLength);metrics.peakQueuedBytes=Math.max(metrics.peakQueuedBytes,bytes);}
+      wakeData?.();wakeData=undefined;controller.enqueue(next.value);
     }catch(error){finish(error);controller.error(error);}},cancel,
   },{highWaterMark:0});
   return {body,cancel,startOutput(){outputStarted=true;},async next(){
     while(head===queue.length&&!done)await new Promise(resolve=>{wakeData=resolve;});
     if(head<queue.length){
-      const parts=[];let size=0;
-      do{const value=queue[head];queue[head++]=undefined;parts.push(value);size+=value.byteLength;}while(head<queue.length&&size+queue[head].byteLength<=32*1024);
+      const first=queue[head];queue[head++]=undefined;
+      let size=first.byteLength,parts;
+      while(head<queue.length&&size+queue[head].byteLength<=32*1024){
+        parts??=[first];const value=queue[head];queue[head++]=undefined;parts.push(value);size+=value.byteLength;
+      }
       bytes-=size;if(head===queue.length){queue.length=0;head=0;}else if(head>=64){queue.splice(0,head);head=0;}
       wakeSpace?.();wakeSpace=undefined;
-      return {value:parts.length===1?parts[0]:Buffer.concat(parts,size),done:false};
+      return {value:parts?Buffer.concat(parts,size):first,done:false};
     }
     if(failure)throw failure;return {done:true};
   }};

package/runtime/html-envelope.mjs

@@ -1,9 +1,39 @@
 import { MAX_RESPONSE_BYTES } from './http.mjs';
 
+const flightScriptEndText = '");document.currentScript.remove()</script>';
+const flightScriptEnd = Buffer.from(flightScriptEndText);
+
+// nonceAttribute is already escaped by the response's HTML renderer. Keep its
+// tiny prefix per response, not a full base64 script string for each chunk.
+// The returned Buffer is owned by the caller and can go straight to transport.
+export function flightBootstrap(nonceAttribute = '') {
+  const start = `<script${nonceAttribute}>(self.__PRNEXT_FLIGHT_STREAM__||=[]).push("`;
+  let prefix, first = true;
+  return value => {
+    if (!(value instanceof Uint8Array) || value.byteLength > MAX_RESPONSE_BYTES) throw new TypeError('Invalid Flight bootstrap bytes');
+    const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    const encoded = bytes.toString('base64');
+    // Most tiny responses finish with one frame. Keep their short original
+    // encoding path instead of paying for a reusable prefix plus three writes.
+    if (first && bytes.byteLength <= 2048) { first = false; return Buffer.from(start + encoded + flightScriptEndText); }
+    first = false;
+    prefix ??= Buffer.from(start);
+    const result = Buffer.allocUnsafe(prefix.length + encoded.length + flightScriptEnd.length);
+    prefix.copy(result);
+    result.write(encoded, prefix.length, encoded.length, 'ascii');
+    flightScriptEnd.copy(result, prefix.length + encoded.length);
+    return result;
+  };
+}
+
 // A raw element cannot be interrupted with a Flight script. Keep its chunks
 // until its closing tag arrives, but only scan newly received characters.
 // Joining and rescanning a growing inline script on every chunk is quadratic.
 const whitespace = /\s/;
+// Complete, unquoted ordinary markup needs no per-tag JS scan. Reject every
+// raw/document/comment candidate (including split prefixes) before this path.
+// Quoted attributes and incomplete tags keep the general streaming parser.
+const specialMarkup = /<(?:!|\?|\/(?:body|html)|script|style|textarea|title|svg|math)/i;
 function holdRaw(state, text) {
   if (!text) return;
   // Compact small chunks in tiers: even single-character input cannot retain
@@ -60,6 +90,10 @@ export function htmlEnvelope({ resumed = false } = {}) {
     append(text) {
       received += Buffer.byteLength(text);
       if (received > MAX_RESPONSE_BYTES) throw new Error('HTML response exceeds the 16 MiB PRNext limit');
+      if (!pending && !rawPending) {
+        if (!text.includes('<') || !text.includes('"') && !text.includes("'") &&
+            !specialMarkup.test(text) && text.lastIndexOf('>') > text.lastIndexOf('<')) return text;
+      }
       let ready = '';
       if (rawPending) {
         const end = rawEnd(text, rawPending);