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

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

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

@@ -199,7 +199,9 @@ async function applyUpdate(message, {navigation=false}={}) {
     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);
+    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 +289,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};
+  };
+}

package/runtime/dev-indicator.mjs

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

package/runtime/dev-lazy-tool.mjs

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

package/runtime/development.mjs

@@ -1,3 +1,4 @@
+import {createDevCompilerBroker} from './dev-compiler-broker.mjs';
 import {spawn} from 'node:child_process';
 import {mkdir,readdir,readFile,writeFile,rm,link,copyFile,realpath,lstat} from 'node:fs/promises';
 import {randomUUID} from 'node:crypto';
@@ -95,7 +96,17 @@ async function runDevelopment(projectRoot,args,binary) {
   let queue=Promise.resolve(),stateQueue=Promise.resolve(),output='.prnext',changes=new Set(),active=new Map(),failed=new Set();
   const failedPaths=new Set();
   const generations=[],styleGenerations=[],retiring=new Set(),pins=new Map(),routeCache=new Map(),filter=createDevChangeFilter(root);
-  const runtimePool=createDevRuntimePool({binary,root,home,environment:{PRNEXT_INSPECT_DIR:diagnosticsDirectory,...(options.profile?{PRNEXT_PROFILE:options.profile}:{})},onChild:child=>captureOutput({stderr:child.stderr,once:child.once.bind(child)},'runtime',{forwardStdout:false})});
+  const compilerBroker=await createDevCompilerBroker({compile:(pattern,sources)=>serialized(async()=>{
+    if(stopping)throw Error('Development is stopping');
+    if(!discovery)await discover();
+    const patterns=[...new Set([pattern,...sources])];
+    if(patterns.some(p=>!discovery.project.routes.some(route=>route.pattern===p)))await discover();
+    if(patterns.some(p=>!discovery.project.routes.some(route=>route.pattern===p)))throw Error('Unknown deferred route pattern');
+    for(const value of patterns)active.set(value,Date.now());
+    if(!current||patterns.some(p=>!current.patterns.has(p)))await rebuild([...active.keys()]);
+    return current.directory;
+  })});
+  const runtimePool=createDevRuntimePool({binary,root,home,environment:{PRNEXT_DEV_COMPILER:compilerBroker.descriptor,PRNEXT_INSPECT_DIR:diagnosticsDirectory,...(options.profile?{PRNEXT_PROFILE:options.profile}:{})},onChild:child=>captureOutput({stderr:child.stderr,once:child.once.bind(child)},'runtime',{forwardStdout:false})});
   const toolSnapshot=()=>({...readyState,safeMode:options.safe,sequence:readyState.sequence??sequence,session,typeErrors,
     routes:(discovery?.project.routes||[]).filter(route=>!route.internal).map(route=>({path:(discovery.config.basePath||'')+(route.pattern==='/'?'/':route.pattern),kind:route.kind,source:route.file?path.relative(root,route.file).replaceAll(path.sep,'/'):undefined,compiled:current?.patterns.has(route.pattern)||false,pinned:[...pins.values()].some(pin=>pin.pattern===route.pattern)})),
     cache:{activeRoutes:active.size,pinnedRoutes:new Set([...pins.values()].map(pin=>pin.pattern)).size,retainedGenerations:generations.length,lookupEntries:routeCache.size,compiler:readyState.compiler,transforms:readyState.transforms,persistentTransforms:true,dependencyIndex:dependencyIndexValid?{valid:true,...current?.manifest.devDependencyIndex}:{valid:false}}});
@@ -140,14 +151,13 @@ async function runDevelopment(projectRoot,args,binary) {
   async function discover(){
     discovery=(await compilerRequest('discover')).discovery;routeCache.clear();output=discovery.config.distDir;
     if(options.safe)discovery={...discovery,eager:true};
-    if(discovery.eager&&!options.safe)console.log('Development uses the complete route graph for middleware, rewrites or parallel routing.');
     const {writeTypedRoutes}=await import('../build/typed-routes.mjs');
     await writeTypedRoutes(root,discovery.project,discovery.config);
     if(!typeChecker||typeChecker.inactive){const {startTypeChecker}=await import('../build/typescript-dev.mjs');typeChecker=await startTypeChecker(root,discovery.config,errors=>{typeErrors=errors;if(!stopping)void writeState().catch(console.error);});}
   }
   async function launch(manifest,directory){
     const runtime=options.safe?undefined:await runtimePool.take(directory).catch(error=>{tools?.addServerLog('warn','Worker warmup was unavailable; starting a fresh worker.',{process:'runtime'});return undefined;});
-    const env={...process.env,NODE_ENV:process.env.NODE_ENV||'development',PRNEXT_INSPECT_DIR:diagnosticsDirectory};
+    const env={...process.env,NODE_ENV:process.env.NODE_ENV||'development',PRNEXT_INSPECT_DIR:diagnosticsDirectory,PRNEXT_DEV_COMPILER:compilerBroker.descriptor};
     delete env.PRNEXT_DEV_BROKER;
     if(runtime)env.PRNEXT_DEV_BROKER=runtime.descriptor;
     const child=spawn(binary,['start',root,'--build-dir',directory,'--worker',path.join(root,directory,'runtime/worker.mjs'),'--node',process.execPath,'--hostname','127.0.0.1','--port','0','--shutdown-on-stdin-eof',...options.backend],{stdio:['pipe','pipe','pipe'],windowsHide:true,env});
@@ -203,30 +213,35 @@ async function runDevelopment(projectRoot,args,binary) {
       current.manifest=manifest;current.changed=changed;current.patterns=new Set(discovery.eager?discovery.project.routes.map(route=>route.pattern):patterns);
       const affected=Object.keys(manifest.app?.actions||{}).length?undefined:affectedRoutes;
       current.affectedRoutes=affected;
-      await writeState({state:'ready',reason,buildId:manifest.buildId,clientManifest:manifest.devClient,sequence:manifest.devSequence,session,changed,affectedRoutes:affected,listenerPid:gateway.child.pid,compiler:result.compiler,transforms:result.transforms,routes:manifest.routes.filter(route=>!route.internal).map(route=>route.pattern)});
+      await writeState({state:'ready',reason,buildId:manifest.buildId,clientManifest:manifest.devClient,sequence:manifest.devSequence,session,changed,affectedRoutes:affected,listenerPid:gateway.child.pid,compiler:result.compiler,transforms:result.transforms,routes:manifest.routes.filter(route=>!route.internal&&!route.devDeferred).map(route=>route.pattern)});
       tools?.recordBuild({buildId:manifest.buildId,reason:reason.summary,reasonCode:reason.code,sequence:manifest.devSequence,time:Date.now(),startedAt,duration:performance.now()-started,phases,routes:patterns.length,state:'ready'});
       console.log('Source compiled. '+reason.summary);
       if(previous){
         const retiringTask=(async()=>{await gateway.request('retire',{generation:previous.id}).catch(()=>{});await previous.runtime?.close();await stop(previous.child);})().finally(()=>retiring.delete(retiringTask));retiring.add(retiringTask);
       }
-      while(generations.length>3){const old=generations.shift();await gateway.request('retire',{generation:old.id});await old.runtime?.close();await stop(old.child);await gateway.request('forget',{generation:old.id});await rm(path.join(root,old.directory),{recursive:true,force:true,maxRetries:10,retryDelay:100});}
+      while(generations.length>3){const old=generations.shift();
+        // A deferred request may itself be awaiting this build. Never wait for
+        // its generation lease while holding the serialized compiler queue.
+        const cleanup=(async()=>{await gateway.request('retire',{generation:old.id});await old.runtime?.close();await stop(old.child);await gateway.request('forget',{generation:old.id});await rm(path.join(root,old.directory),{recursive:true,force:true,maxRetries:10,retryDelay:100});})().catch(error=>{if(!stopping)console.warn('Development generation cleanup: '+error.message);}).finally(()=>retiring.delete(cleanup));retiring.add(cleanup);
+      }
       await watcher?.refresh();
       return manifest;
     }catch(error){if(!stopping){tools?.recordBuild({sequence,reason:reason.summary,reasonCode:reason.code,time:Date.now(),startedAt,duration:performance.now()-started,phases,state:'error'});tools?.addServerLog('error',error.message,{process:'compiler'});console.error('Build failed: '+error.message);await writeState({state:'error',reason,error:error.message});}throw error;}
   }
   const updateInfo=()=>({buildId:current.manifest.buildId,clientManifest:current.manifest.devClient,pagesManifest:current.manifest.pagesManifest,sequence:current.manifest.devSequence,session,changed:current.changed,cssOnly:current.cssOnly,affectedRoutes:current.affectedRoutes});
-  async function ensure(raw,client){
-    const warm=discovery&&findRoute(raw);
+  async function ensure(raw,client,exact=false){
+    const resolve=()=>exact?discovery.project.routes.find(route=>route.pattern===raw):findRoute(raw);
+    const warm=discovery&&resolve();
     if(!stopping&&current&&warm&&active.has(warm.pattern)&&current.patterns.has(warm.pattern)){
       active.set(warm.pattern,Date.now());if(pins.has(client))pins.get(client).pattern=warm.pattern;
       return updateInfo();
     }
     return serialized(async()=>{
     if(!discovery)try{await discover();}catch(error){failedPaths.add(raw);await writeState({state:'error',error:error.message});throw error;}
-    let route=findRoute(raw);
+    let route=resolve();
     // A newly written route can be requested before the watcher's debounce.
     // Resolve that miss against the filesystem instead of returning a stale 404.
-    if(!route){await discover();route=findRoute(raw);}
+    if(!route){await discover();route=resolve();}
     if(route)active.set(route.pattern,Date.now());
     if(route&&pins.has(client))pins.get(client).pattern=route.pattern;
     const max=Math.max(0,Math.min(64,discovery.config.onDemandEntries?.pagesBufferLength??5));
@@ -235,7 +250,8 @@ async function runDevelopment(projectRoot,args,binary) {
     const inactive=[...active].filter(([pattern])=>!pinned.has(pattern)).sort((a,b)=>a[1]-b[1]);
     const age=Math.min(86400000,discovery.config.onDemandEntries?.maxInactiveAge??60000);
     while(inactive.length>max&&(Date.now()-inactive[0][1]>=age||active.size>64+pinned.size))active.delete(inactive.shift()[0]);
-    if(!current || route&&!current.patterns.has(route.pattern)){
+    const graphChanged=current&&discovery.project.routes.some(candidate=>!current.manifest.routes.some(built=>built.id===candidate.id));
+    if(!current || graphChanged || route&&!current.patterns.has(route.pattern)){
       try{await rebuild([...active.keys()]);}catch(error){if(route){failed.add(route.pattern);active.delete(route.pattern);}throw error;}
     }
     return updateInfo();
@@ -273,7 +289,7 @@ async function runDevelopment(projectRoot,args,binary) {
       // Node process has drained after() work and cache fills on stdin EOF.
       await runtimePool.close();
       await Promise.all([tools?.close(),...generations.map(g=>stop(g.child)),...retiring]);
-      await queue.catch(()=>{});await stateQueue;await rm(home,{recursive:true,force:true,maxRetries:10,retryDelay:100});await rm(stateFile,{force:true});
+      await queue.catch(()=>{});await compilerBroker.close();await stateQueue;await rm(home,{recursive:true,force:true,maxRetries:10,retryDelay:100});await rm(stateFile,{force:true});
     })();return closing;
   };
   const fatal=error=>{if(!stopping){console.error(error.message);process.exitCode=1;void shutdown();}};
@@ -298,7 +314,8 @@ async function runDevelopment(projectRoot,args,binary) {
     }
     console.log(`PRNext development · http://${options.hostname.includes(':')?'['+options.hostname+']':options.hostname}:${listener.port} · on-demand routes`);
     if(options.safe)console.log('Safe mode: full route builds, fresh compilers and no worker warmup.');
-    watcher=await watchProject(root,{ignore:relative=>relative===output||relative.startsWith(output+'/'),onError:fatal,onChange:file=>{
+    watcher=await watchProject(root,{ignore:relative=>relative===output||relative.startsWith(output+'/'),onError:fatal,onChange:(file,event)=>{
+      typeChecker?.invalidate?.(file,event);
       if(stopping||!shouldWatchProjectFile(file))return;changes.add(String(file).replaceAll(path.sep,'/'));clearTimeout(timer);timer=setTimeout(()=>void serialized(changed).catch(()=>{}),75);
     }});
     await serialized(discover).catch(async error=>{console.error('Build failed: '+error.message);await writeState({state:'error',error:error.message});});

package/runtime/document.mjs

@@ -64,7 +64,7 @@ export async function renderDocument({ Document = DefaultDocument, App = Default
     throw new TypeError('Document.getInitialProps must return an object with an html string');
   }
   if (Buffer.byteLength(initial.html) > MAX_RESPONSE_BYTES) throw new Error('Response exceeds the 16 MiB PRNext limit');
-  const payload = { props, appProps, router: snapshot, buildId, route: { pattern: snapshot.pathname }, dynamicIds: [...dynamicModules] };
+  const payload = { props, appProps, router: snapshot, buildId, ...(manifest?.config?.deploymentId ? {deploymentId:manifest.config.deploymentId} : {}), route: { pattern: snapshot.pathname }, dynamicIds: [...dynamicModules] };
   const assetPrefix = manifest?.config?.assetPrefix || manifest?.config?.basePath || '';
   const nextData = { props: { ...appProps, pageProps: props }, page: snapshot.pathname, query: snapshot.query, buildId,
     ...(snapshot.locale ? {locale:snapshot.locale,locales:snapshot.locales,defaultLocale:snapshot.defaultLocale} : {}),

package/runtime/edge.mjs

@@ -75,14 +75,15 @@ async function createEdgeVM(reactMode) {
 export async function loadEdgeModule(code, name, reactMode) {
   if (reactMode !== undefined && reactMode !== 'rsc' && reactMode !== 'ssr') throw new Error('Unknown Edge React mode');
   let pending;
-  if (reactMode) {
-    pending = reactVMs.get(reactMode);
+  {
+    const key=reactMode||'handler';
+    pending = reactVMs.get(key);
     if (!pending) {
       pending = createEdgeVM(reactMode);
-      reactVMs.set(reactMode, pending);
-      void pending.catch(() => { if (reactVMs.get(reactMode) === pending) reactVMs.delete(reactMode); });
+      reactVMs.set(key, pending);
+      void pending.catch(() => { if (reactVMs.get(key) === pending) reactVMs.delete(key); });
     }
-  } else pending = createEdgeVM();
+  }
   // This runtime module belongs to one compiled build. Its two React realms
   // are shared lazily by all pages/boundaries; each bundle has its own factory.
   const vm = await pending;

package/runtime/fetch-cache.mjs

@@ -1,3 +1,4 @@
+import {withTrace,propagatedFetch} from './trace.mjs';
 import { createHash } from 'node:crypto';
 import cache from '../compat/data-cache.cjs';
 import { dynamicUsage, trackStaticDependency } from '../compat/static-generation.cjs';
@@ -12,6 +13,7 @@ const MAX_MEMO_BYTES = 8 * 1024 * 1024;
 const CAPTURE_IDLE_MS = 1000;
 const CAPTURE_LIFETIME_MS = 20_000;
 let registration;
+const telemetryFetch=(input,init)=>nativeFetch(...propagatedFetch(input,init));
 
 class UncacheableResponse extends Error {
   constructor(response) { super('The fetch response is not cacheable'); this.response = response; }
@@ -305,24 +307,24 @@ export function installFetchCache() {
           }, error => { diagnostics.record('fetch', { ...fields, error: true, durationMs: performance.now() - started }); throw error; });
         }
       }
-      return nativeFetch(input, init);
+      return telemetryFetch(input, init);
     };
     Object.defineProperty(fetch, PATCHED, { value: dispatcher });
     globalThis.fetch = fetch;
   }
   if (registration && dispatcher.handlers.includes(registration)) return globalThis.fetch;
   async function fetch(input, init, context) {
-    if (context.phase === 'pages' || init?.next?.internal) return nativeFetch(input, init);
+    if (context.phase === 'pages' || init?.next?.internal) return telemetryFetch(input, init);
     if (inCacheScope()) {
       const next = init?.next || input?.next || {};
       if (next.revalidate !== undefined && next.revalidate !== false && (typeof next.revalidate !== 'number' || Number.isNaN(next.revalidate) || next.revalidate < 0)) throw new TypeError('fetch next.revalidate must be a nonnegative number or false');
       recordCacheDependency(next);
-      return nativeFetch(input, init);
+      return telemetryFetch(input, init);
     }
     const policy = fetchPolicy(input, init, context);
     if (context.staticState) trackStaticDependency({ tags: policy.tags, paths: getCachePaths(context),
       revalidate: context.cacheConfig?.dynamic === 'force-static' && policy.revalidate === 0 ? null : policy.revalidate }, context);
-    if (init?.dispatcher || init?.agent) return nativeFetch(input, init);
+    if (init?.dispatcher || init?.agent) return telemetryFetch(input, init);
     const state = cacheState(context);
     const explicitSignal = init?.signal !== undefined || input instanceof Request;
     const method = String(init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
@@ -331,9 +333,9 @@ export function installFetchCache() {
     const persist = policy.persist && !hardRefresh && !context.draftMode && !context.cacheConfig?.forceNoStore;
     if (diagnostics.enabled && !persist) diagnostics.record('cache', { route: diagnostics.route(context), state: 'bypass',
       reason: context.draftMode ? 'draft mode' : hardRefresh ? 'development hard refresh' : context.cacheConfig?.forceNoStore ? 'route disables caching' : 'fetch policy does not opt into persistent caching' });
-    if (!persist && !memoize) return nativeFetch(input, init);
+    if (!persist && !memoize) return telemetryFetch(input, init);
     const prepared = await prepareRequest(input, init);
-    if (!prepared) return nativeFetch(input, init);
+    if (!prepared) return telemetryFetch(input, init);
     const request = prepared.request;
     request.signal.throwIfAborted();
     const memo = memoize ? memoState(state) : null;
@@ -361,7 +363,7 @@ export function installFetchCache() {
       entry = undefined;
     }
     const producer = async ({ background = false, signal, cache: canPersist = true } = {}) => {
-      const response = await nativeFetch(request, background && signal ? { signal: AbortSignal.any([request.signal, signal]) } : undefined);
+      const response = await telemetryFetch(request, background && signal ? { signal: AbortSignal.any([request.signal, signal]) } : undefined);
       // Set-Cookie responses must not replay a session mutation, even when the
       // request itself explicitly opted into shared caching.
       if (response.headers.has('set-cookie') || (persist && response.status !== 200) || (!canPersist && !entry)) throw new UncacheableResponse(response);
@@ -384,7 +386,7 @@ export function installFetchCache() {
       throw error;
     }
   }
-  registration = { context: optionalRequestContext, fetch };
+  registration = { context: optionalRequestContext, fetch:(input,init,context)=>withTrace({kind:3},'prnext.fetch',()=>fetch(input,init,context)) };
   dispatcher.handlers.push(registration);
   return globalThis.fetch;
 }