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

package/runtime/app-stream-html.mjs

@@ -1,3 +1,4 @@
+import {reportRequestError,acknowledgeRequestError} from './instrumentation.mjs';
 import { htmlEnvelope } from './html-envelope.mjs';
 import React from 'react';
 import { fontPreloads } from './font-preload.mjs';
@@ -12,55 +13,9 @@ import { addBasePath } from '../compat/paths.cjs';
 import { renderAppRecoveryShell } from './app-recovery.mjs';
 import { partialModel } from './app-partial-model.mjs';
 import { streamSelector } from './stream-select.mjs';
+import {nodeHtmlReader,useNodeHtml} from './node-html-stream.mjs';
 
-// The SSR decoder and HTML bootstrap share each Flight allocation. Unlike
-// ReadableStream.tee(), this tap stops reading when the HTML consumer stalls.
-// Before a document shell exists, at most the overall 16 MiB response limit can
-// accumulate: an async root layout may need the complete model to produce it.
-function flightTap(source) {
-  const reader = source.getReader();
-  const queue = [];
-  let bytes = 0;
-  let done = false;
-  let failure;
-  let outputStarted = false;
-  let wakeData;
-  let wakeSpace;
-  const finish = error => {
-    done = true; failure = error;
-    wakeData?.(); wakeData = undefined;
-    wakeSpace?.(); wakeSpace = undefined;
-  };
-  const cancel = async reason => { finish(reason); await reader.cancel(reason).catch(() => {}); };
-  const body = new ReadableStream({
-    async pull(controller) {
-      try {
-        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);
-      } catch (error) { finish(error); controller.error(error); }
-    },
-    cancel,
-  }, { highWaterMark: 0 });
-  return {
-    body, cancel,
-    startOutput() { outputStarted = true; },
-    async next() {
-      while (!queue.length && !done) await new Promise(resolve => { wakeData = resolve; });
-      if (queue.length) {
-        const value = queue.shift(); bytes -= value.byteLength;
-        wakeSpace?.(); wakeSpace = undefined;
-        return { value, done: false };
-      }
-      if (failure) throw failure;
-      return { done: true };
-    },
-  };
-}
+import {flightTap} from './flight-tap.mjs';
 
 export async function renderProgressiveAppHtml({ result, request, route, responseHeaders, decodeFlight, signal, timeoutMs, partial }) {
   timeoutMs ??= route?.cacheConfig?.maxDuration ? route.cacheConfig.maxDuration * 1000 : 25_000;
@@ -92,6 +47,7 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
       onError(error) {
         if (isDynamicBailout(error)) return error.digest;
         if (combinedSignal.aborted) return error?.digest;
+        if(result.reportedDigests?.has(error?.digest))acknowledgeRequestError(error);else reportRequestError(error);
         const navigation = navigationResponse(error);
         if (navigation) {
           if (committed) control = navigation;
@@ -104,8 +60,9 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
     const element = React.createElement(request.strictMode !== false ? React.StrictMode : React.Fragment, null, React.createElement(AppRouterProvider, { router: resumedModel.router, nonce: request.nonce }, appContent(resumedModel.tree)));
     // React owns and mutates its opaque continuation during resume. Parsed
     // artifacts can be shared, but each HTML request needs its own continuation.
-    const html = partial ? await resume(element, structuredClone(partial.postponed), renderOptions) : await renderToReadableStream(element, renderOptions);
-    reader = html.getReader();
+    reader = !partial&&request.cacheConfig?.runtime!=='edge'&&useNodeHtml()
+      ? await nodeHtmlReader(element,renderOptions)
+      : (partial ? await resume(element, structuredClone(partial.postponed), renderOptions) : await renderToReadableStream(element, renderOptions)).getReader();
     const decoder = new TextDecoder();
     let prefix = partial?.shell || '';
     let htmlDone = false;
@@ -116,13 +73,13 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
       const next = await reader.read();
       if (next.done) { htmlDone = true; prefix += decoder.decode(); break; }
       prefix += decoder.decode(next.value, { stream: true });
-      if (Buffer.byteLength(prefix) > MAX_RESPONSE_BYTES) throw new Error('HTML shell exceeds the 16 MiB PRNext limit');
+      if (Buffer.byteLength(prefix) > MAX_RESPONSE_BYTES) throw Object.assign(new Error('HTML shell exceeds the 16 MiB PRNext limit'),{code:'PRNEXT_RESPONSE_TOO_LARGE'});
     }
     if (renderError) throw renderError;
     if (!/<html(?:\s|>)/i.test(prefix) || !/<body(?:\s|>)/i.test(prefix) || !/<\/head>/i.test(prefix)) {
       throw Object.assign(new Error('App Router root layout must render <html>, <head> and <body> elements'), { code: 'PRNEXT_INVALID_ROOT_LAYOUT' });
     }
-    const styles = fontPreloads(route.fonts, request.nonce) + (route.css || []).map(href => `<link rel="stylesheet" href="${escapeHtml(href)}">`).join('');
+    const styles = fontPreloads(route.fonts, request.nonce) + (model.css ?? route.css ?? []).map(href => `<link rel="stylesheet" href="${escapeHtml(href)}">`).join('');
     if (styles && !partial) prefix = prefix.replace(/<\/head>/i, `${styles}</head>`);
     tap.startOutput();
     committed = true;
@@ -183,7 +140,7 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
     return { status, headers: { ...responseHeaders, ...result.headers, 'content-type': 'text/html; charset=utf-8' }, body, cancel };
   } catch (error) {
     if (!committed && !combinedSignal.aborted && error?.statusCode !== 504 &&
-        error?.code !== 'PRNEXT_INVALID_ROOT_LAYOUT' && !isDynamicBailout(error) && (!navigationResponse(error) || (route.parallel && navigationResponse(error).status === 404))) {
+        error?.code !== 'PRNEXT_INVALID_ROOT_LAYOUT' && error?.code !== 'PRNEXT_RESPONSE_TOO_LARGE' && !isDynamicBailout(error) && (!navigationResponse(error) || (route.parallel && navigationResponse(error).status === 404))) {
       try {
         // Next emits an empty document after a shell failure. The original
         // Flight stream still carries the failing subtree to client boundaries;

package/runtime/app-style-selection.mjs

@@ -0,0 +1,34 @@
+function ownsBranch(scope, branch) {
+  const path = branch.replace(/#default$/, '');
+  if (scope.kind === 'layout') return !scope.path || path === scope.path || path.startsWith(scope.path + '/');
+  return path === scope.path && (scope.kind === 'default') === branch.endsWith('#default');
+}
+
+/** Parallel route entries include both canonical and intercepted alternatives.
+ * Their actual router selection determines which sheets may become active. */
+export function selectAppStyles(model) {
+  if (!model.routing || !Array.isArray(model.cssScopes)) return;
+  const branches = Object.values(model.routing.slots || {}).map(slot => slot.branch);
+  model.cssScopes = model.cssScopes.filter(scope => (scope.kind === 'layout' && !scope.path) || branches.some(branch => ownsBranch(scope, branch)));
+  model.css = [...new Set(model.cssScopes.flatMap(scope => scope.css || []))];
+}
+
+/** A retained parallel/intercepted slot keeps only the styles belonging to
+ * that branch. Carrying the preceding route's complete list would leak its
+ * inactive page globals into the new main page. */
+export function retainAppStyles(model, previous) {
+  selectAppStyles(model);
+  if (!model.routing || !previous?.routing || model.globalError) return;
+  const retained = Object.entries(model.routing.slots || {}).flatMap(([key, slot]) => {
+    const old = previous.routing.slots?.[key];
+    return old && old.branch === slot.branch && old.url === slot.url ? [slot.branch] : [];
+  });
+  if (!retained.length) return;
+  const scopes = [...model.cssScopes || []];
+  for (const scope of previous.cssScopes || []) {
+    if (scopes.some(current => current.path === scope.path && current.kind === scope.kind)) continue;
+    if (retained.some(branch => ownsBranch(scope, branch))) scopes.push(scope);
+  }
+  model.cssScopes = scopes;
+  model.css = [...new Set([...(model.css || []), ...scopes.flatMap(scope => scope.css || [])])];
+}

package/runtime/app-styles.mjs

@@ -0,0 +1,154 @@
+const managers = new WeakMap();
+
+function aborted() { return new DOMException('Navigation cancelled', 'AbortError'); }
+
+/** Styles are downloaded while the old page remains visible, but become
+ * active together in the new tree's layout effect, before the next paint.
+ * Keeping one manager per document also covers development runtime updates. */
+export function appStyleManager(document, { timeout = 15_000 } = {}) {
+  if (managers.has(document)) return managers.get(document);
+  const sheets = new Map();
+  let handed = new Map();
+  let cleanup = 0;
+  const reserved = sheet => handed.get(sheet.link.href) === sheet;
+  function urls(values) {
+    if (!Array.isArray(values) || values.length > 1024) throw new Error('Invalid App Router stylesheet list');
+    return [...new Set(values.map(value => {
+      if (typeof value !== 'string' || value.length > 4096) throw new Error('Invalid App Router stylesheet URL');
+      const url = new URL(value, document.baseURI);
+      if (!['http:', 'https:'].includes(url.protocol)) throw new Error('Invalid App Router stylesheet protocol');
+      return url.href;
+    }))];
+  }
+  function remove(href, sheet) {
+    if (sheet.removed) return;
+    sheet.removed = true;
+    sheet.detach?.();
+    sheet.link.remove();
+    const records = sheets.get(href);
+    if (records) {
+      const index = records.indexOf(sheet);
+      if (index >= 0) records.splice(index, 1);
+      if (!records.length) sheets.delete(href);
+    }
+  }
+  function acquire(href, before, replace = false) {
+    const records = sheets.get(href) || [];
+    const current = records.at(-1);
+    if (current && !replace) return current;
+    // A replacement keeps the old active (or local-reset recovery) occurrence
+    // in place until commit. Discard older abandoned candidates immediately.
+    if (replace) for (const record of [...records]) if (!record.active && !record.recovery && !reserved(record)) remove(href, record);
+    const tracked = new Set(records.map(record => record.link));
+    const existing = replace ? undefined : [...document.querySelectorAll('link[rel="stylesheet"]')].find(link => link.href === href && !tracked.has(link));
+    const link = existing || document.createElement('link');
+    const sheet = { link, active: !!existing, ready: !!existing?.sheet, recovery: false };
+    const retained = sheets.get(href) || [];
+    retained.push(sheet); sheets.set(href, retained);
+    if (sheet.ready) sheet.promise = Promise.resolve();
+    else sheet.promise = new Promise((resolve, reject) => {
+      let finished = false;
+      const detach = () => { clearTimeout(timer); link.removeEventListener('load', loaded); link.removeEventListener('error', failed); };
+      const finish = error => {
+        if (finished) return;
+        finished = true; detach(); sheet.detach = undefined;
+        if (error) { remove(href, sheet); reject(error); }
+        else { sheet.ready = true; resolve(); }
+      };
+      const loaded = () => finish();
+      const failed = () => finish(new Error(`Could not load stylesheet ${href}`));
+      const timer = setTimeout(() => finish(new Error('App Router stylesheet loading timed out')), timeout);
+      sheet.detach = () => finish(aborted());
+      link.addEventListener('load', loaded);
+      link.addEventListener('error', failed);
+    });
+    // Cancellation and a competing navigation can remove a pending sheet.
+    // Each caller still observes the original rejection through prepare().
+    void sheet.promise.catch(() => {});
+    if (!existing) {
+      link.rel = 'stylesheet'; link.href = href; link.media = 'not all';
+      link.dataset.prnextAppStyle = '';
+      if (before) document.head.insertBefore(link, before);
+      else document.head.append(link);
+    }
+    return sheet;
+  }
+  const manager = {
+    async prepare(values = [], signal) {
+      if (signal?.aborted) throw aborted();
+      const wanted = urls(values);
+      const prepared = [];
+      let before;
+      // Establish cascade order before downloading. Re-inserting an already
+      // loaded link can unload its CSSOM and refetch, even within the same head.
+      // Keep a correctly ordered suffix; prepare a separate inactive occurrence
+      // when an existing sheet would otherwise need to move across that suffix.
+      for (let index = wanted.length - 1; index >= 0; index--) {
+        const href = wanted[index];
+        let sheet = acquire(href, before);
+        if (before && !(sheet.link.compareDocumentPosition(before) & 4)) sheet = acquire(href, before, true);
+        prepared.push(sheet.promise);
+        before = sheet.link;
+      }
+      const pending = Promise.all(prepared);
+      if (!signal) return pending;
+      await new Promise((resolve, reject) => {
+        const cancel = () => reject(aborted());
+        signal.addEventListener('abort', cancel, { once: true });
+        pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', cancel));
+      });
+    },
+    handoff(values = []) {
+      // A concurrent React render can suspend after its CSS has loaded. Pin
+      // these exact occurrences until that render commits or is superseded;
+      // pagehide/actions must cancel network work, not its already-ready CSS.
+      const next = new Map(urls(values).map(href => {
+        const sheet = sheets.get(href)?.at(-1);
+        if (!sheet?.ready) throw new Error('App Router styles were not prepared before rendering');
+        return [href, sheet];
+      }));
+      const previous = handed; handed = next;
+      for (const [href, sheet] of previous) if (!reserved(sheet) && !sheet.active && !sheet.recovery) remove(href, sheet);
+    },
+    commit(values = []) {
+      cleanup++;
+      const wanted = new Set(urls(values));
+      const handedUrls = [...handed.keys()];
+      const pinned = wanted.size === handed.size && [...wanted].every((href, index) => handedUrls[index] === href) ? handed : null;
+      for (const href of wanted) {
+        const records = sheets.get(href) || [];
+        const prior = !pinned && handed.size ? records.find(record => record.active) || records.find(record => record.recovery) : undefined;
+        const sheet = pinned?.get(href) || prior || records.findLast(record => record.ready) || acquire(href);
+        // Initial HTML links are render-blocking. A missing sheet is restored
+        // on explicit recovery; normal navigation always prepares first.
+        sheet.active = true; sheet.recovery = false; sheet.link.media = '';
+        for (const previous of [...sheets.get(href)]) if (previous !== sheet && !reserved(previous)) remove(href, previous);
+      }
+      if (pinned) handed = new Map();
+      for (const [href, records] of sheets) {
+        for (const sheet of [...records]) if ((!wanted.has(href) || !sheet.active) && !reserved(sheet)) remove(href, sheet);
+      }
+    },
+    release() {
+      const revision = ++cleanup;
+      // A normal tree update or StrictMode's effect replay commits in the same
+      // turn. Only a genuine fatal/global unmount retires the normal styles.
+      queueMicrotask(() => {
+        if (cleanup !== revision) return;
+        const recovery = new Set([...sheets.values()].flat().filter(sheet => sheet.ready && (sheet.active || reserved(sheet))));
+        for (const [href, records] of sheets) for (const sheet of [...records]) {
+          // Local reset is allowed to remount the same server tree without a
+          // request. Keep already loaded sheets inert so that reset can restore
+          // them synchronously, rather than painting before a second load event.
+          if (recovery.has(sheet)) { sheet.active = false; sheet.recovery = true; sheet.link.media = 'not all'; }
+          else if (recovery.size || !sheet.recovery) remove(href, sheet);
+        }
+      });
+    },
+    cancel() {
+      for (const [href, records] of sheets) for (const sheet of [...records]) if (!sheet.active && !sheet.recovery && !reserved(sheet)) remove(href, sheet);
+    },
+  };
+  managers.set(document, manager);
+  return manager;
+}

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

@@ -44,7 +44,10 @@ globalThis[codecSymbol] = {
     const bundler = flightBundler(context.clientModules, false);
     let failure;
     // React calls then inside its rendering context, preserving React.cache isolation.
-    const result = { then(resolve, reject) { Promise.resolve().then(callback).then(resolve, reject); } };
+    // React can subscribe more than once while unwrapping a thenable. Start
+    // lazily in its rendering context, but never execute the producer twice.
+    let execution;
+    const result = { then(resolve, reject) { (execution ||= Promise.resolve().then(callback)).then(resolve, reject); } };
     const stream = renderToReadableStream(result, bundler, { signal: context.signal, temporaryReferences: encoded.serverTemporaryReferences, onError(error) { failure ||= error; return 'PRNextCacheRenderError'; } });
     const chunks = [];
     let size = 0;
@@ -54,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/cache-request.mjs

@@ -1,3 +1,4 @@
+import {reportRequestError} from './instrumentation.mjs';
 import { runRequestContext, currentRequest } from '../compat/headers.cjs';
 import { flushCacheInvalidations, flushCacheWork } from '../compat/data-cache.cjs';
 import { createAfterScope } from '../compat/after.cjs';
@@ -9,7 +10,7 @@ export function withCacheRequest(options, phase, callback) {
   // only needs metadata, and may survive the response for stale revalidation.
   return runRequestContext({ ...options, body: undefined, routePattern: options.route?.pattern, cacheConfig: options.route?.cacheConfig, phase }, async () => {
     const context = currentRequest();
-    if (phase === 'route' && options.route?.cacheConfig?.runtime !== 'edge') context.afterScope = createAfterScope({ signal: options.signal, timeoutMs: options.timeoutMs ?? (options.route?.cacheConfig?.maxDuration ? options.route.cacheConfig.maxDuration * 1000 : 25000) });
+    if (phase === 'route' && options.route?.cacheConfig?.runtime !== 'edge') context.afterScope = createAfterScope({report:error=>{console.error('[prnext] after() failed:',error?.stack||error);return reportRequestError(error);}, signal: options.signal, timeoutMs: options.timeoutMs ?? (options.route?.cacheConfig?.maxDuration ? options.route.cacheConfig.maxDuration * 1000 : 25000) });
     let finalized;
     const finalizeCache = () => finalized ||= (async () => { await context.afterScope?.finish(); await flushCacheWork(context); })();
     // The worker owns response completion even when application code throws.

package/runtime/deployment-client.mjs

@@ -0,0 +1,19 @@
+const HEADER = 'x-prnext-deployment-id';
+
+/** A generation is an artifact identity, independent from a user-supplied buildId. */
+export function deploymentHeaders(id) { return id ? { [HEADER]: id } : {}; }
+
+export async function assertDeploymentResponse(response, expected) {
+  if (response.headers.get('x-prnext-document-navigation') === '1') {
+    await response.body?.cancel().catch(() => {});
+    const error = new Error('This route requires a full document navigation.');
+    error.code = 'PRNEXT_DOCUMENT_NAVIGATION';
+    throw error;
+  }
+  if (!expected) return;
+  if (response.headers.get(HEADER) === expected && response.status !== 409) return;
+  await response.body?.cancel().catch(() => {});
+  const error = new Error('This page belongs to a previous deployment. Reload the page before continuing.');
+  error.code = 'PRNEXT_DEPLOYMENT_CHANGED';
+  throw error;
+}

package/runtime/dev-client.mjs

@@ -195,11 +195,18 @@ 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; }
-    await updateStyles(kind === 'pages' ? route.css : manifest.app.css);
+    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),...(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
     // selection until application code changes, rather than racing diagnostics.
@@ -287,7 +294,10 @@ function connect(options) {
     if (message.buildId === state.buildId) return;
     // A cold navigation may receive SSE readiness before its ensure response.
     // Updating modules is safe; refreshing the old route would cancel the click.
-    void applyUpdate(message,{navigation:state.ensuring>0});
+    // A retained branch can become cold after ensure() has returned. Its
+    // worker-triggered compilation is still part of the pending navigation;
+    // committing a refresh here would abort it and restore the previous URL.
+    void applyUpdate(message,{navigation:state.ensuring>0||message.reason?.code==='route-opened'});
   };
   globalThis.addEventListener('error', event => { if (event.error) showError(event.error); });
   globalThis.addEventListener('unhandledrejection', event => showError(event.reason));

package/runtime/dev-compiler-broker.mjs

@@ -0,0 +1,42 @@
+import http from 'node:http';
+import {randomBytes,timingSafeEqual} from 'node:crypto';
+import {readFile,realpath} from 'node:fs/promises';
+import path from 'node:path';
+
+// 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--;}
+  });
+  server.requestTimeout=125000;server.headersTimeout=5000;
+  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();})};
+}
+
+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');
+  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 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'));
+    if(!manifest.dev||manifest.devSession!==path.basename(parent))throw Error('Invalid development generation');
+    return {distDir:directory,manifest};
+  };
+}