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

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

package/runtime/flight-delta.mjs

@@ -0,0 +1,74 @@
+import { randomBytes, createHmac } from 'node:crypto';
+import { deflateRawSync } from 'node:zlib';
+import { TYPE, MAX_VALUE, collectStream, deltaStream } from '../compat/flight-delta.cjs';
+
+export function createFlightStore({maxBytes=32*1024*1024,maxEntries=64,ttl=30000,maxCaptures=8,maxEncoders=2,now=Date.now,setTimer=setTimeout,clearTimer=clearTimeout}={}) {
+  if(!Number.isFinite(ttl)||ttl<0||typeof now!=='function'||typeof setTimer!=='function'||typeof clearTimer!=='function')throw new TypeError('Invalid Flight store expiration policy');
+  const entries=new Map();let size=0,captures=0,encoders=0,timer,timerExpires;
+  function reserve(kind){if(kind==='capture'?captures>=maxCaptures:encoders>=maxEncoders)return;kind==='capture'?captures++:encoders++;let released=false;return()=>{if(released)return;released=true;kind==='capture'?captures--:encoders--;};}
+  function remove(token){const entry=entries.get(token);if(entry){size-=entry.bytes.length;entries.delete(token);}}
+  function schedule(at){
+    let expires=Infinity;
+    for(const entry of entries.values())expires=Math.min(expires,entry.expires);
+    if(timer!==undefined&&timerExpires===expires)return;
+    if(timer!==undefined)clearTimer(timer);
+    timer=timerExpires=undefined;
+    if(!entries.size)return;
+    timerExpires=expires;
+    // One timer for the bounded store, not one per response. A cancelled cache
+    // entry must not leave its former deadline armed. Clamp long TTLs to Node's
+    // timer range; an early wake simply checks the authoritative clock again.
+    const handle=setTimer(()=>{
+      if(timer!==handle)return;
+      timer=timerExpires=undefined;prune(true);
+    },Math.min(2147483647,Math.max(1,expires-at)));
+    timer=handle;timer?.unref?.();
+  }
+  function prune(changed=false){
+    const at=now();
+    for(const[token,entry]of entries)if(entry.expires<=at){remove(token);changed=true;}
+    while(size>maxBytes||entries.size>maxEntries){remove(entries.keys().next().value);changed=true;}
+    // Ordinary hits keep the same timer without another full entry scan.
+    if(changed)schedule(at);
+  }
+  return {
+    get(token,identity){prune();const entry=entries.get(token);if(entry?.identity!==identity)return;return entry?.bytes;},
+    set(token,identity,bytes){if(bytes.length>MAX_VALUE)return;remove(token);entries.set(token,{identity,bytes,expires:now()+ttl});size+=bytes.length;prune(true);},
+    capture:()=>reserve('capture'),encoder:()=>reserve('encoder'),get inFlight(){return {captures,encoders};},
+    get bytes(){return size;},get size(){return entries.size;},
+  };
+}
+const store=createFlightStore();
+export function compressedDeltaPolicy(acceptEncoding='') {
+  const compressed=acceptEncoding.split(',').some(value=>{
+    const [name,...parameters]=value.trim().toLowerCase().split(';');
+    return /^(gzip|deflate|br|zstd|\*)$/.test(name)&&!parameters.some(p=>/^\s*q\s*=\s*0(?:\.0*)?\s*$/.test(p));
+  });
+  if(!compressed)return;
+  // This conservative, bounded probe is not the response compressor. It avoids
+  // choosing thousands of references to JSON that gzip already compresses well.
+  // A large/expensive chunk keeps ordinary Flight instead of delaying a flush.
+  return (raw,encoded)=>raw.length<=64*1024&&encoded.length+32<raw.length&&
+    deflateRawSync(encoded,{level:1}).length+32<deflateRawSync(raw,{level:1}).length*0.9;
+}
+export async function differentialFlight(response,options,cache=store) {
+  const headers=new Headers(options.headers), outgoing=new Headers(response.headers);
+  if((options.method||'GET')!=='GET'||headers.get('rsc')!=='1'||headers.get('x-prnext-flight-accept')!=='v1'||headers.get('x-prnext-prefetch')==='1'||response.status!==200||!outgoing.get('content-type')?.startsWith('text/x-component'))return response;
+  const secret=options.manifest?.app?.actionKey;if(!secret)return response;
+  const identity=createHmac('sha256',secret).update(JSON.stringify([options.manifest.cacheId,headers.get('cookie')||'',headers.get('authorization')||''])).digest('hex');
+  const releaseCapture=cache.capture(),token=releaseCapture?randomBytes(24).toString('hex'):undefined,previous=headers.get('x-prnext-flight-base'),candidate=cache.get(previous,identity),releaseEncoder=candidate&&cache.encoder(),base=releaseEncoder?candidate:undefined;
+  let encoded;
+  try{
+    const raw=response.body;
+    const body=raw instanceof ReadableStream?raw:raw?.[Symbol.asyncIterator]?ReadableStream.from(raw):new ReadableStream({start(controller){
+      controller.enqueue(raw instanceof Uint8Array?raw:raw instanceof ArrayBuffer?new Uint8Array(raw):new TextEncoder().encode(String(raw??'')));controller.close();
+    }});
+    const collected=collectStream(body,{capture:!!releaseCapture,onComplete:bytes=>cache.set(token,identity,bytes),onFinally:releaseCapture});
+    encoded=base?await deltaStream(collected,base,{assess:compressedDeltaPolicy(headers.get('accept-encoding')||'')}):{delta:false,body:collected};
+    if(!encoded.delta)releaseEncoder?.();
+    else encoded.body=collectStream(encoded.body,{capture:false,onFinally:releaseEncoder});
+  }catch(error){releaseEncoder?.();releaseCapture?.();throw error;}
+  if(token)outgoing.set('x-prnext-flight-token',token);else outgoing.delete('x-prnext-flight-token');outgoing.set('cache-control','private, no-store');outgoing.delete('content-length');
+  if(encoded.delta){outgoing.set('content-type',TYPE);outgoing.set('x-prnext-flight-base',previous);}
+  return {...response,headers:Object.fromEntries(outgoing),body:encoded.body,cancel:reason=>{releaseEncoder?.();releaseCapture?.();void encoded.body.cancel(reason).catch(()=>{});return response.cancel?.(reason);}};
+}

package/runtime/flight-tap.mjs

@@ -0,0 +1,28 @@
+// 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) {
+  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;};
+  const cancel=reason=>cancelled??=(async()=>{finish(reason);queue.length=0;head=0;bytes=0;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(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);
+      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};
+    }
+    if(failure)throw failure;return {done:true};
+  }};
+}

package/runtime/fs.mjs

@@ -1,15 +1,22 @@
 import { rename as move } from 'node:fs/promises';
 import { setTimeout as delay } from 'node:timers/promises';
+import path from 'node:path';
 
 // Windows scanners and recently closed file handles can briefly deny rename.
 // Keep the atomic swap: never delete the destination to work around a lock.
-export async function rename(source, destination) {
-  const deadline = Date.now() + 2000;
-  for (let attempt = 0; ; attempt++) {
-    try { return await move(source, destination); }
-    catch (error) {
-      if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || Date.now() >= deadline) throw error;
-      await delay(Math.min(10 * (attempt + 1), 100));
+export function createAtomicRenamer({moveFile=move,wait=delay,platform=process.platform,now=()=>performance.now(),retryMs=2000}={}) {
+  return async function rename(source,destination) {
+    const started=now(),deadline=started+retryMs;
+    for(let attempt=1;;attempt++){
+      try{return await moveFile(source,destination);}
+      catch(error){
+        if(platform!=='win32'||!['EPERM','EACCES','EBUSY'].includes(error.code)||now()>=deadline){
+          error.atomicRename={operation:'rename',code:error.code||'UNKNOWN',attempts:attempt,elapsedMs:Math.max(0,now()-started),destination:path.basename(destination)};
+          throw error;
+        }
+        await wait(Math.min(10*attempt,100,Math.max(0,deadline-now())));
+      }
     }
-  }
+  };
 }
+export const rename=createAtomicRenamer();

package/runtime/html-only.mjs

@@ -0,0 +1,27 @@
+/** Reject executable markup instead of silently stripping author content or
+ * React reveal instructions. HTML-only documents must already be complete. */
+export function assertHtmlOnlyDocument(html, pattern = '') {
+  const fail = reason => { throw new Error(`htmlOnly route ${pattern} emitted ${reason}. Use static HTML elements without JavaScript.`); };
+  if (typeof html !== 'string') fail('an invalid HTML document');
+  if (/<\s*(?:script|iframe|object|embed)(?=[\s/>])/i.test(html)) fail('a script or embedded browsing context');
+  const tags = /<[a-z][^<>"']*(?:(?:"[^"]*"|'[^']*')[^<>"']*)*>/gi;
+  const attributes = /([^\s/>=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+  const decode = value => value.replace(/&#(?:x([\da-f]+)|(\d+));?/gi, (_, hex, decimal) => String.fromCodePoint(Math.min(0x10ffff, parseInt(hex || decimal, hex ? 16 : 10)))).replace(/&(?:colon|tab|newline);/gi, entity => ({'&colon;':':','&tab;':'\t','&newline;':'\n'})[entity.toLowerCase()]);
+  for (const match of html.matchAll(tags)) {
+    const tag = match[0], start = /^<[\w:-]+/.exec(tag)[0].length;
+    const values = new Map();
+    for (const attribute of tag.slice(start).matchAll(attributes)) {
+      const name = attribute[1].toLowerCase(), value = decode(attribute[2] ?? attribute[3] ?? attribute[4] ?? '');
+      // HTML ignores later duplicate attributes; preserve the same first value
+      // when interpreting link token lists and resource destinations.
+      if (!values.has(name)) values.set(name,value);
+      if (/^on[a-z]/.test(name) || name === 'srcdoc') fail(`interactive attribute ${name}`);
+      if (name === 'name' && value.startsWith('$ACTION_')) fail('a Server Action form');
+      if (['href','src','action','formaction','xlink:href'].includes(name)) {
+        if (/^javascript:/i.test(value.replace(/[\u0000-\u0020]/g, ''))) fail('a JavaScript URL');
+      }
+    }
+    if (/^<link\b/i.test(tag) && ((values.get('rel') || '').toLowerCase().split(/[\t\n\f\r ]+/).includes('modulepreload') || (values.get('as') || '').trim().toLowerCase() === 'script')) fail('a JavaScript preload');
+  }
+  return html;
+}

package/runtime/http.mjs

@@ -1,3 +1,4 @@
+import {reportRequestError} from './instrumentation.mjs';
 import { createRequire } from 'node:module';
 // ESM node:http evaluates lazy WebSocket exports and initializes Undici.
 // Use the module object to avoid that startup cost while preserving HTTP patches.
@@ -186,6 +187,7 @@ export function plainResponse(status, message) {
 }
 
 export function errorResponse(error, production = process.env.NODE_ENV === 'production') {
+  reportRequestError(error);
   console.error('[prnext]', error?.stack || error);
   const status = [400, 503, 504].includes(error?.statusCode) ? error.statusCode : 500;
   const message = status === 400 ? 'Bad Request' : status === 503 ? 'Service Unavailable' : status === 504 ? 'Gateway Timeout' : 'Internal Server Error';

package/runtime/incremental-cache.mjs

@@ -35,6 +35,20 @@ export async function runIncrementalCache(options) {
   const input = JSON.parse(Buffer.from(options.body, 'base64').toString());
   if (!input || typeof input.key !== 'string' || input.key.length > 8192 || !kinds.has(input.kind)) throw new Error('Invalid incremental cache key or kind');
   const context = { ...options, cacheHandler: options.manifest.config.cacheHandler, cacheMaxMemorySize: options.manifest.config.cacheMaxMemorySize };
+  if (input.op === 'acquire' || input.op === 'release') {
+    const { handler } = await legacy.load(context);
+    if (input.op === 'release') {
+      if (handler.prnextLeaseVersion === 1 && typeof handler.release === 'function' && input.lease) await legacy.invoke(handler, 'release', [input.key, input.lease], context);
+      return empty(204);
+    }
+    if (handler.prnextLeaseVersion !== 1 || typeof handler.acquire !== 'function') return empty(204);
+    let lease;
+    try { lease = await legacy.invoke(handler, 'acquire', [input.key, { signal: options.signal }], context); }
+    catch (error) { if (error.code === 'PRNEXT_REDIS_BUSY') return empty(425); throw error; }
+    const encoded = JSON.stringify(lease);
+    if (!lease || encoded.length > 4096 || /[\r\n]/.test(encoded)) throw new Error('Invalid incremental cache generation lease');
+    return { ...empty(204), headers: { 'x-prnext-cache-lease': encoded } };
+  }
   if (input.op === 'invalidate') {
     await legacy.invalidate(context, { tags: input.tags, mode: 'expire' });
     return empty(204);
@@ -54,7 +68,8 @@ export async function runIncrementalCache(options) {
     }
     const tags = [...new Set([...info.tags, ...implicit(info.paths)])];
     if (tags.length) value.headers = { ...value.headers, 'x-next-cache-tags': tags.join(',') };
-    await legacy.setEntry(input.key, value, context, { tags, cacheControl: { revalidate: info.revalidate }, isRoutePPREnabled: false });
+    const stored = await legacy.setEntry(input.key, value, context, { tags, cacheControl: { revalidate: info.revalidate }, isRoutePPREnabled: false, prnextLease: input.lease });
+    if (stored === false) return empty(409);
     return empty(204);
   }
   if (input.op !== 'get') throw new Error('Unknown incremental cache operation');
@@ -73,11 +88,17 @@ export async function runIncrementalCache(options) {
     data = input.kind === 'APP_PAGE' ? bytes(value.rscData) : Buffer.from(JSON.stringify(value.pageData));
   }
   if (html.length + data.length > MAX_BYTES) throw new Error('Incremental cache entry exceeds 16 MiB');
-  const cacheVersion = createHash('sha256').update(JSON.stringify([entry.lastModified, value.status, value.headers, info])).update(html).update(data).digest('hex');
+  const softStale = entry.isStale === true;
+  const cacheVersion = createHash('sha256').update(JSON.stringify([entry.lastModified, softStale, value.status, value.headers, info])).update(html).update(data).digest('hex');
   if (input.knownVersion === cacheVersion) return { ...empty(304), headers: { 'x-prnext-cache-version': cacheVersion } };
   const headers = { ...value.headers }; delete headers['x-next-cache-tags'];
+  // A positive expired generation uses native stale-while-revalidate. -1/zero
+  // remains the existing hard-expiration path. The cacheVersion above stays
+  // stable even when replicas have slightly different wall clocks.
+  const revalidate = softStale && info.revalidate === false ? 1 : info.revalidate;
+  const lastModified = softStale ? Math.max(0, Math.min(Date.now(), entry.lastModified) - Math.max(1, revalidate || 1) * 1000 - 1) : entry.lastModified;
   return { status: value.status, headers, body: [html, data],
-    isr: { ...(input.kind === 'APP_ROUTE' ? { kind: 'route' } : {}), revalidate: entry.lastModified < 0 ? 0 : info.revalidate,
+    isr: { ...(input.kind === 'APP_ROUTE' ? { kind: 'route' } : {}), revalidate: entry.lastModified < 0 ? 0 : revalidate,
       htmlLength: html.length, dataLength: data.length, tags: info.tags, paths: info.paths,
-      lastModified: entry.lastModified, cacheVersion } };
+      lastModified, cacheVersion } };
 }

package/runtime/instrumentation.mjs

@@ -0,0 +1,49 @@
+import {withTrace,markTraceError} from './trace.mjs';
+import {readFile} from 'node:fs/promises';
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {pathToFileURL} from 'node:url';
+import path from 'node:path';
+import {isControlError} from './navigation.mjs';
+
+const modules=new Map(),scope=new AsyncLocalStorage(),reported=new WeakSet();
+function bounded(promise,milliseconds,label){
+  let timer;
+  return Promise.race([Promise.resolve(promise),new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error(label+' timed out')),milliseconds);})]).finally(()=>clearTimeout(timer));
+}
+export function initializeInstrumentation(distDir,manifest,{realm='node',reactMode,loader}={}) {
+  const file=manifest.instrumentation?.[realm];if(!file)return Promise.resolve({});
+  const filename=path.resolve(distDir,file),key=filename+':'+(reactMode||realm);let pending=modules.get(key);
+  loader??=realm==='edge'?async file=>{const {loadEdgeModule}=await import('./edge.mjs');const asset=file.replace(/\.mjs$/,'.edge.js');return loadEdgeModule(await readFile(asset,'utf8'),asset,reactMode);}:file=>import(pathToFileURL(file).href);
+  if(!pending){
+    pending=(async()=>{const module=await loader(filename);if(module.register!==undefined&&typeof module.register!=='function')throw Error('instrumentation.register must be a function');if(module.onRequestError!==undefined&&typeof module.onRequestError!=='function')throw Error('instrumentation.onRequestError must be a function');await bounded(Promise.resolve().then(()=>module.register?.()),30000,'instrumentation.register');return module;})();
+    // Retain failures too: a failed initialization must never run application code.
+    modules.set(key,pending);
+  }
+  return pending;
+}
+export function wasRequestErrorReported(error){return !!error&&typeof error==='object'&&(error.instrumentationReported===true||reported.has(error));}
+export function acknowledgeRequestError(error){if(error&&typeof error==='object'){scope.getStore()?.seen.add(error);reported.add(error);}markTraceError();}
+export function reportRequestError(error,extra={}) {
+  if(isControlError(error))return;markTraceError();
+  const state=scope.getStore();if(error?.instrumentationReported===true||!state?.module.onRequestError||state.reporting)return;
+  const value=error&&typeof error==='object'?error:new Error(String(error));
+  if(state.seen.has(value)||state.seen.size>=32)return;state.seen.add(value);reported.add(value);
+  const pending=scope.run({...state,reporting:true},()=>bounded(Promise.resolve().then(()=>state.module.onRequestError(value,state.request,{...state.context,...extra})),5000,'instrumentation.onRequestError')).catch(()=>{console.error('[prnext] instrumentation.onRequestError failed');});
+  state.pending.add(pending);void pending.finally(()=>state.pending.delete(pending));return pending;
+}
+export async function withInstrumentation(options,callback,{realm='node',module}={}) {
+  const edge=options.route?.cacheConfig?.runtime==='edge'||options.route?.handlerConfig?.runtime==='edge'||options.route?.runtime==='edge';
+  const renderRealm=realm;
+  if(edge)realm='edge';
+  module??=await initializeInstrumentation(options.distDir,options.manifest||{},{realm,reactMode:edge&&options.route?.router==='app'&&options.route?.kind==='page'?(renderRealm==='rsc'?'rsc':'ssr'):undefined});
+  const traced=()=>withTrace(options,renderRealm==='rsc'?'prnext.rsc':'prnext.node',callback);
+  if(!module.onRequestError)return traced();
+  const url=new URL(options.originalUrl||options.url||'http://localhost/'),route=options.route||{};
+  const request=Object.freeze({path:url.pathname+url.search,method:options.method||'GET',headers:Object.freeze(Object.fromEntries(new Headers(options.headers)))});
+  const context={routerKind:route.router==='app'?'App Router':'Pages Router',routePath:route.pattern||options.routePattern||url.pathname,
+    routeType:options.action||new Headers(options.headers).has('next-action')?'action':route.kind==='middleware'?'proxy':route.kind==='api'?'route':'render',
+    renderSource:renderRealm==='rsc'?'react-server-components':new Headers(options.headers).get('rsc')==='1'?'react-server-components-payload':'server-rendering',
+    revalidateReason:['stale','on-demand'].includes(options.revalidateReason)?options.revalidateReason:undefined,renderType:options.partialFlight?'dynamic-resume':'dynamic'};
+  const state={module,request,context,seen:new Set(),pending:new Set()};
+  return scope.run(state,async()=>{try{return await traced();}catch(error){if(!options.signal?.aborted||error?.statusCode===504)reportRequestError(error);throw error;}finally{await Promise.all([...state.pending]);}});
+}

package/runtime/lazy-import-client.mjs

@@ -0,0 +1,38 @@
+// Only emitted by the opt-in development compiler. Successful imports retain
+// native ESM caching; failed compilation is retryable after a source correction.
+const pending=new Map(),styles=new Map();
+function stylesheet(url){
+  const existing=[...document.querySelectorAll('link[rel="stylesheet"]')].find(link=>link.href===new URL(url,location.href).href);
+  if(existing?.sheet)return Promise.resolve();
+  if(existing&&styles.has(url))return styles.get(url);
+  const promise=new Promise((resolve,reject)=>{
+    const link=existing||document.createElement('link');
+    const timer=setTimeout(()=>finish(Error('Deferred stylesheet timed out')),30000);
+    const finish=error=>{clearTimeout(timer);link.removeEventListener('load',loaded);link.removeEventListener('error',failed);if(error){styles.delete(url);if(!existing)link.remove();reject(error);}else resolve();};
+    const loaded=()=>finish(),failed=()=>finish(Error('Deferred stylesheet failed to load'));
+    link.addEventListener('load',loaded,{once:true});link.addEventListener('error',failed,{once:true});
+    if(!existing){link.rel='stylesheet';link.href=url;document.head.appendChild(link);}
+  });
+  styles.set(url,promise);
+  void promise.then(()=>styles.delete(url),()=>styles.delete(url));
+  return promise;
+}
+export function lazyImport(id,basePath=''){
+  const key=basePath+':'+id;
+  if(pending.has(key))return pending.get(key);
+  const task=(async()=>{
+    const path='/_prnext/lazy/'+id;
+    const response=await fetch(`${basePath}/_prnext/ensure?path=${encodeURIComponent(path)}`,{cache:'no-store',credentials:'same-origin',signal:AbortSignal.timeout(120000)});
+    if(!response.ok)throw Error(await response.text());
+    const value=await response.json(),target=value.lazy;
+    if(!target||typeof target.url!=='string'||!Array.isArray(target.css))throw Error('Invalid deferred import response');
+    for(const url of [target.url,...target.css]){
+      const parsed=new URL(url,location.href);
+      if(parsed.origin!==location.origin||!parsed.pathname.includes('/_prnext/assets/'))throw Error('Invalid deferred import asset URL');
+    }
+    await Promise.all(target.css.map(stylesheet));
+    const module=await import(target.url);
+    return target.native?module:module.__prnextLazyModule;
+  })().finally(()=>pending.delete(key));
+  pending.set(key,task);return task;
+}

package/runtime/navigation-recovery.mjs

@@ -0,0 +1,36 @@
+import offline from '../compat/offline-store.cjs';
+
+export function networkFailure(error){
+  return error?.name==='NetworkError'||((error instanceof TypeError||error?.name==='TypeError')&&/fetch|network|load failed|terminated/i.test(error.message||''))||/^Connection closed\.?$/.test(error?.message||'');
+}
+function waitForConnection({signal,events,online,milliseconds,waitingOffline}){
+  return new Promise((resolve,reject)=>{
+    const finish=callback=>value=>{clearTimeout(timer);signal?.removeEventListener('abort',aborted);events?.removeEventListener('online',connected);callback(value);};
+    const done=finish(resolve),fail=finish(reject),aborted=()=>fail(signal.reason||new DOMException('Navigation cancelled','AbortError'));
+    const connected=()=>{if(online())done();};
+    const timer=setTimeout(()=>done(),milliseconds);
+    signal?.addEventListener('abort',aborted,{once:true});events?.addEventListener('online',connected);
+    if(signal?.aborted)aborted();
+    else if(waitingOffline&&online())done();
+  });
+}
+// Called exclusively around navigation GETs. Server Actions never enter this
+// path: a lost response does not prove their mutation failed to execute.
+export async function recoverNavigation(read,{signal,events=globalThis.window,online=()=>globalThis.navigator?.onLine!==false,budgetMs=30000,maxAttempts=3}={}){
+  const until=performance.now()+budgetMs;let waiting,lastError,attempts=0;
+  const failure=()=>Object.assign(new Error('Unable to load the page. Check your connection and try again.',{cause:lastError}),{code:'PRNEXT_NAVIGATION_NETWORK'});
+  const deadline=new AbortController(),combined=signal?AbortSignal.any([signal,deadline.signal]):deadline.signal;
+  const timer=setTimeout(()=>deadline.abort(failure()),budgetMs);
+  try{
+    for(;;){
+      combined.throwIfAborted();
+      if(online()||attempts===0){
+        try{return await read(combined);}catch(error){if(combined.aborted)throw combined.reason;if(!networkFailure(error))throw error;lastError=error;attempts++;waiting||=offline.beginWait();}
+      }
+      const remaining=until-performance.now();
+      if(remaining<=0||attempts>=maxAttempts)throw failure();
+      const waitingOffline=!online();
+      await waitForConnection({signal:combined,events,online,waitingOffline,milliseconds:Math.min(remaining,waitingOffline?remaining:250*2**Math.max(0,attempts-1))});
+    }
+  }finally{clearTimeout(timer);waiting?.();}
+}

package/runtime/navigation.mjs

@@ -14,3 +14,10 @@ export function navigationResponse(error) {
   if (!['http:', 'https:'].includes(parsed.protocol)) return null;
   return { status, headers: { location: destination, 'cache-control': 'no-store' }, body: Buffer.alloc(0) };
 }
+
+/** Expected routing/render controls must not become application error reports. */
+export function isControlError(error) {
+  return !!navigationResponse(error) || error?.digest === 'BAILOUT_TO_CLIENT_SIDE_RENDERING'
+    || error?.code === 'PRNEXT_DYNAMIC_SERVER_USAGE' || error?.code === 'PRNEXT_PPR_DYNAMIC'
+    || error?.digest === 'PRNEXT_PPR_DYNAMIC';
+}

package/runtime/node-html-stream.mjs

@@ -0,0 +1,47 @@
+import {Writable} from 'node:stream';
+import {renderToPipeableStream} from 'react-dom/server';
+
+// One bounded Node stream, without a second Web reader queue. Partial React
+// continuations keep using their original Web API and opaque resume state.
+export function nodeHtmlReader(element,options={}){
+  return new Promise((resolve,reject)=>{
+    const {signal,...renderOptions}=options;
+    let renderer,settled=false,finished=false,slot,pending,acknowledge,failure;
+    const cleanup=()=>signal?.removeEventListener('abort',aborted);
+    const deliver=()=>{
+      if(!pending)return;
+      const {resolve,reject}=pending;
+      if(failure){pending=undefined;reject(failure);}
+      else if(slot){pending=undefined;const current=slot;slot=undefined;acknowledge=current.done;resolve({value:current.chunk,done:false});}
+      else if(finished){pending=undefined;resolve({done:true});}
+    };
+    // A single writable replaces PassThrough's writable+readable machinery.
+    // Keep its write callback until the next read: React may reuse a chunk only
+    // after its consumer has finished, and native backpressure stays bounded.
+    const stream=new Writable({highWaterMark:64*1024,
+      write(chunk,_encoding,done){slot={chunk,done};deliver();},
+      final(done){finished=true;cleanup();deliver();done();},
+    });
+    const fail=error=>{failure=error;if(!settled){settled=true;cleanup();reject(error);}deliver();stream.destroy(error);};
+    stream.on('error',error=>{failure=error;cleanup();deliver();});
+    const aborted=()=>{const error=signal.reason||new Error('HTML render was cancelled');renderer?.abort(error);fail(error);};
+    if(signal?.aborted){aborted();return;}
+    signal?.addEventListener('abort',aborted,{once:true});
+    try{
+      renderer=renderToPipeableStream(element,{...renderOptions,onShellError:fail,onShellReady(){
+        if(settled)return;settled=true;
+        resolve({
+          read(){
+            if(pending)return Promise.reject(new Error('HTML reads must be sequential.'));
+            const done=acknowledge;acknowledge=undefined;done?.();
+            return new Promise((resolve,reject)=>{pending={resolve,reject};deliver();});
+          },
+          async cancel(reason){if(finished)return;finished=true;cleanup();renderer.abort(reason);const done=acknowledge||slot?.done;acknowledge=undefined;slot=undefined;stream.destroy();done?.();deliver();},
+          releaseLock(){if(finished)cleanup();},
+        });
+        renderer.pipe(stream);
+      }});
+    }catch(error){fail(error);}
+  });
+}
+export const useNodeHtml=()=>process.env.PRNEXT_SSR_STREAM==='node';

package/runtime/pages-client.mjs

@@ -1,3 +1,4 @@
+import { deploymentHeaders, assertDeploymentResponse } from './deployment-client.mjs';
 import React from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import Router, { RouterProvider, useRouter, installPagesRouter } from '../compat/router.cjs';
@@ -62,9 +63,10 @@ async function readPageData(response, limit = MAX_DATA_BYTES, { discard = false,
 }
 
 export async function readPageDataResponse(response, visibleURL, {
-  maxBytes = MAX_DATA_BYTES, includeBytes = false, fetcher = globalThis.fetch, signal, requestURL = visibleURL,
+  maxBytes = MAX_DATA_BYTES, includeBytes = false, deploymentId, fetcher = globalThis.fetch, signal, requestURL = visibleURL,
 } = {}) {
   try {
+    await assertDeploymentResponse(response, deploymentId);
     let legacy = false;
     for (let redirects = 0; response.headers.get('x-prnext-legacy-navigation') === '1'; redirects++) {
       legacy = true;
@@ -79,7 +81,8 @@ export async function readPageDataResponse(response, visibleURL, {
       await response.body?.cancel();
       signal?.throwIfAborted();
       response = await fetcher(target.href, { credentials: 'same-origin', redirect: 'follow', signal,
-        headers: { accept: 'application/json', 'x-nextjs-data': '1', 'x-prnext-navigation': '1' } });
+        headers: { ...deploymentHeaders(deploymentId), accept: 'application/json', 'x-nextjs-data': '1', 'x-prnext-navigation': '1' } });
+      await assertDeploymentResponse(response, deploymentId);
       requestURL = target.href;
     }
     if (legacy && !response.ok && (response.status < 300 || response.status >= 400)) throw new Error(`Page data request failed (${response.status})`);
@@ -140,9 +143,10 @@ function pagesView(props) {
 }
 
 let application;
-async function startPages({ Page, App, pattern, manifestUrl, basePath = '', trailingSlash = false, skipTrailingSlashRedirect = false, assetBase, strictMode = false }) {
+async function startPages({ deploymentId, Page, App, pattern, manifestUrl, basePath = '', trailingSlash = false, skipTrailingSlashRedirect = false, assetBase, strictMode = false }) {
   const data = window.__PRNEXT_DATA__;
   if (!data?.router || !data.props) throw new Error('Missing PRNext page data');
+  if (deploymentId && deploymentId !== data.deploymentId) throw new Error('The document and its JavaScript belong to different deployments.');
   const rewrite = readRewriteMarker(document);
   const initial = { ...data, router: { ...data.router, basePath, trailingSlash, skipTrailingSlashRedirect }, Page, App, ...(rewrite ? { rewrite } : {}) };
   let buildId = data.buildId;
@@ -163,13 +167,13 @@ async function startPages({ Page, App, pattern, manifestUrl, basePath = '', trai
       if (signal.aborted) cancel();
       const timer = setTimeout(() => abort.abort(new Error('Page data request timed out')), 30_000);
       try {
-        const requestURL = pageDataURL(buildId, url.href, basePath);
+        const requestURL = pageDataURL(window.__PRNEXT_STATIC_EXPORT__ && deploymentId ? buildId + '~' + deploymentId : buildId, url.href, basePath);
         const response = await fetcher(requestURL, {
           credentials: 'same-origin', redirect: 'manual', signal: abort.signal,
-          headers: { accept: 'application/json', 'x-nextjs-data': '1', 'x-prnext-navigation': '1', ...(speculative ? { purpose: 'prefetch' } : {}) },
+          headers: { ...deploymentHeaders(deploymentId), accept: 'application/json', 'x-nextjs-data': '1', 'x-prnext-navigation': '1', ...(speculative ? { purpose: 'prefetch' } : {}) },
         });
         return await readPageDataResponse(response, url.href, { maxBytes: speculative ? 2 * 1024 * 1024 : MAX_DATA_BYTES,
-          includeBytes: speculative, fetcher, signal: abort.signal, requestURL });
+          deploymentId: window.__PRNEXT_STATIC_EXPORT__ ? undefined : deploymentId, includeBytes: speculative, fetcher, signal: abort.signal, requestURL });
       } finally { clearTimeout(timer); signal.removeEventListener('abort', cancel); }
     },
   });
@@ -201,6 +205,9 @@ export function bootstrapPages(options) {
   if (process.env.NODE_ENV === 'development' && options.dev && globalThis.__PRNEXT_DEV__) {
     return globalThis.__PRNEXT_DEV__.bootstrap('pages', options, () => startPages(options));
   }
-  application ||= startPages(options);
+  if (!application) {
+    application = startPages(options);
+    void application.catch(error => console.error('[PRNext] Pages startup failed:', error));
+  }
   return application;
 }