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

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/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,23 +167,32 @@ 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); }
     },
   });
   installPagesRouter(controller);
   let resolveHydration;
   const hydrated = new Promise(resolve => { resolveHydration = resolve; });
-  root = hydrateRoot(container, pagesView({ state: initial, strictMode, committed: resolveHydration, reportError: controller.reportRenderError }));
+  root = hydrateRoot(container, pagesView({ state: initial, strictMode, committed: resolveHydration, reportError: controller.reportRenderError }), process.env.NODE_ENV === 'development' ? {
+    onRecoverableError(error, info) {
+      console.error(error);
+      globalThis.__PRNEXT_DEV__?.reportRecoverableError(error, info);
+    },
+  } : undefined);
   await hydrated;
   if (data.router.isFallback) void controller.refreshFallback();
   return { root, router: controller, ...(process.env.NODE_ENV === 'development' ? {
+    devSync(options) {
+      buildId=options.dev.buildId;window.__PRNEXT_DATA__.buildId=buildId;
+      controller.devSetManifest({buildId,manifestUrl:options.manifestUrl});
+    },
     async devCommit(options) {
       buildId = options.dev.buildId;
       window.__PRNEXT_DATA__.buildId = buildId;
@@ -192,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;
 }

package/runtime/pages-navigation.mjs

@@ -4,7 +4,10 @@ import { rewriteQuery } from '../compat/rewrite.cjs';
 import { normalizeBasePath, removeBasePath } from '../compat/paths.cjs';
 import { publicNavigationURL, isApplicationURL } from './client-navigation.mjs';
 import DefaultError from '../compat/error.cjs';
+import { createPrefetchScheduler, prefetchCacheVictim } from './prefetch-scheduler.mjs';
 import { applicationProps, createInitialPropsRunner } from './pages-initial-props.mjs';
+import { matchPagePattern } from './route-pattern.mjs';
+export { matchPagePattern } from './route-pattern.mjs';
 
 const PREFETCH_LIMIT = 8;
 const PREFETCH_TTL = 30_000;
@@ -51,33 +54,6 @@ export function pageRouterSnapshot(router, requestURL, visibleURL, rewrite) {
     ...(rewrite ? { rewrite } : {}) };
 }
 
-export function matchPagePattern(pattern, pathname) {
-  let segments;
-  try { segments = pathname.replace(/\/+$/, '').split('/').slice(1).map(decodeURIComponent); }
-  catch { return null; }
-  if (segments.length === 1 && !segments[0]) segments = [];
-  if (segments.some(segment => !segment || /[/\\\0]/.test(segment) || segment === '.' || segment === '..')) return null;
-  const parts = pattern === '/' ? [] : pattern.split('/').slice(1), params = Object.create(null), rank = [];
-  let index = 0;
-  for (const part of parts) {
-    const optional = /^\[\[\.\.\.([^\]]+)\]\]$/.exec(part);
-    const catchall = /^\[\.\.\.([^\]]+)\]$/.exec(part);
-    const parameter = /^\[([^\]]+)\]$/.exec(part);
-    if (optional || catchall) {
-      if (catchall && index === segments.length) return null;
-      if (index !== segments.length) params[(optional || catchall)[1]] = segments.slice(index);
-      index = segments.length; rank.push(optional ? 0 : 1);
-    } else if (parameter) {
-      if (index === segments.length) return null;
-      params[parameter[1]] = segments[index++]; rank.push(2);
-    } else {
-      if (segments[index++] !== part) return null;
-      rank.push(3);
-    }
-  }
-  return index === segments.length ? { params, rank } : null;
-}
-
 export function resolvePageRoute(manifest, pathname) {
   let winner;
   for (const [routes, pages] of [[manifest.routes, true], [manifest.nonPagesRoutes || [], false]]) {
@@ -129,7 +105,8 @@ export function createPagesNavigation({ initial, initialRoute, manifestUrl, read
   initial = undefined;
   let manifestPromise, active, renderingError, sequence = 0, beforePop = () => true;
   let currentKey = win.history.state?.__prnextPages?.key || 0, nextKey = currentKey + 1;
-  const prefetches = new Map(), queue = []; let prefetchRunning = 0, prefetchBytes = 0;
+  const prefetches = new Map(), scheduler = createPrefetchScheduler({ window: win, document: doc });
+  let prefetchBytes = 0;
 
   function assetURL(value) {
     const url = new URL(value, win.location.href);
@@ -147,7 +124,7 @@ export function createPagesNavigation({ initial, initialRoute, manifestUrl, read
       const abort = new AbortController(), timer = setTimeout(() => abort.abort(), 30_000);
       try {
         const value = JSON.parse(await consume(await fetchAsset(manifestUrl, abort.signal), ASSET_LIMIT));
-        if (value.buildId !== buildId || !Array.isArray(value.routes) || value.routes.length > 10_000) throw new Error('Invalid Pages manifest');
+        if (value.buildId !== buildId || current.deploymentId && value.deploymentId !== current.deploymentId || !Array.isArray(value.routes) || value.routes.length > 10_000) throw new Error('Invalid Pages manifest');
         for (const route of [...value.routes, ...Object.values(value.errors || {}).filter(Boolean)]) {
           if (typeof route.pattern !== 'string' || !Array.isArray(route.css)) throw new Error('Invalid page route');
           assetURL(route.client); for (const css of route.css) assetURL(css);
@@ -278,44 +255,45 @@ export function createPagesNavigation({ initial, initialRoute, manifestUrl, read
     prefetchBytes -= entry.bytes || 0; entry.bytes = 0;
     if (abort) entry.abort.abort(); else entry.consumed = true;
   }
-  function pumpPrefetch() {
-    while (prefetchRunning < 2 && queue.length) {
-      const entry = queue.shift();
-      if (entry.abort.signal.aborted) { entry.resolve(); continue; }
-      prefetchRunning++;
-      (async () => {
-        const map = await abortable(manifest(), entry.abort.signal), matched = resolvePageRoute(map, internalPath(entry.request));
-        if (!matched?.pages) return;
-        // Fetch rather than evaluate speculative modules: fetch is cancellable,
-        // whereas the browser's import() cannot cancel a blocked module request.
-        await consume(await fetchAsset(matched.route.client, entry.abort.signal), ASSET_LIMIT);
-        if (entry.abort.signal.aborted) return;
-        // Warm browser HTTP caches without applying another page's CSS early.
-        for (const css of matched.route.css) await consume(await fetchAsset(css, entry.abort.signal), ASSET_LIMIT);
-        if (matched.route.ssg) {
-          const decoded = await requestData(entry.request, entry.abort.signal, true);
-          if (entry.abort.signal.aborted || (!prefetches.has(entry.key) && !entry.consumed) || decoded.cacheable === false) return;
-          entry.data = decoded;
-          if (entry.consumed) return;
-          entry.bytes = decoded.bytes || 0; prefetchBytes += entry.bytes;
-          while (prefetchBytes > PREFETCH_BYTES) dropPrefetch(prefetches.keys().next().value);
-        }
-      })().catch(() => { dropPrefetch(entry.key); }).finally(() => { prefetchRunning--; entry.resolve(); pumpPrefetch(); });
+  async function runPrefetch(entry) {
+    const map = await abortable(manifest(), entry.abort.signal), matched = resolvePageRoute(map, internalPath(entry.request));
+    if (!matched?.pages) return;
+    // Fetch rather than evaluate speculative modules: fetch can be cancelled,
+    // whereas import() can leave an uncancellable module request in flight.
+    await consume(await fetchAsset(matched.route.client, entry.abort.signal), ASSET_LIMIT);
+    if (entry.abort.signal.aborted) return;
+    for (const css of matched.route.css) await consume(await fetchAsset(css, entry.abort.signal), ASSET_LIMIT);
+    if (matched.route.ssg) {
+      const decoded = await requestData(entry.request, entry.abort.signal, true);
+      if (entry.abort.signal.aborted || (prefetches.get(entry.key) !== entry && !entry.consumed) || decoded.cacheable === false) return;
+      entry.data = decoded;
+      if (entry.consumed) return;
+      entry.bytes = decoded.bytes || 0; prefetchBytes += entry.bytes;
+      while (prefetchBytes > PREFETCH_BYTES) {
+        const victim = prefetchCacheVictim([...prefetches].filter(([, value]) => value.bytes > 0), 1);
+        if (victim === undefined) break;
+        dropPrefetch(victim);
+      }
     }
   }
-  function prefetch(url, as, options) {
+  function prefetch(url, as, options = {}) {
     let request;
     try { ({ request } = targets(url, as, options)); } catch { return Promise.resolve(); }
     if (!isApplicationURL(request, win.location.origin, basePath) || process.env.NODE_ENV !== 'production') return Promise.resolve();
     request.hash = ''; const key = request.href;
-    if (prefetches.has(key)) return prefetches.get(key).promise;
-    while (prefetches.size >= PREFETCH_LIMIT) dropPrefetch(prefetches.keys().next().value);
-    // Queued cancelled entries must not grow with an unbounded list of hovered links.
-    for (let index = queue.length - 1; index >= 0; index--) if (queue[index].abort.signal.aborted) { queue[index].resolve(); queue.splice(index, 1); }
-    const entry = { key, request, abort: new AbortController() };
-    entry.promise = new Promise(resolve => { entry.resolve = resolve; });
+    const priority = options.priority === 'viewport' ? 0 : 1;
+    const previous = prefetches.get(key);
+    if (previous && !previous.abort.signal.aborted) { previous.priority = Math.max(previous.priority, priority); previous.task.promote(options.priority); return previous.promise; }
+    if (previous) dropPrefetch(key);
+    const victim = prefetches.size >= PREFETCH_LIMIT ? prefetchCacheVictim(prefetches, priority) : undefined;
+    if (prefetches.size >= PREFETCH_LIMIT && victim === undefined) return Promise.resolve();
+    const entry = { key, request, priority, abort: new AbortController() };
+    entry.task = scheduler.schedule(() => runPrefetch(entry), { abort: entry.abort, priority: options.priority });
+    if (!entry.task) return Promise.resolve();
+    if (victim !== undefined) dropPrefetch(victim);
+    entry.promise = entry.task.promise.catch(() => { if (prefetches.get(key) === entry) dropPrefetch(key); });
     entry.timer = setTimeout(() => dropPrefetch(key), PREFETCH_TTL);
-    prefetches.set(key, entry); queue.push(entry); pumpPrefetch(); return entry.promise;
+    prefetches.set(key, entry); return entry.promise;
   }
   function cancelActive() {
     if (!active) return;
@@ -328,9 +306,13 @@ export function createPagesNavigation({ initial, initialRoute, manifestUrl, read
   async function navigate(url, as, options = {}) {
     let { request, destination } = targets(url, as, options);
     if (!isApplicationURL(destination, win.location.origin, basePath) || !isApplicationURL(request, win.location.origin, basePath)) { hard(destination, options.replace); return true; }
+    if(process.env.NODE_ENV==='development'&&!options.devRefresh)await globalThis.__PRNEXT_DEV__?.ensureRoute?.(request.href);
     cancelActive(); renderingError?.abort.abort(); renderingError = undefined; saveScroll();
     const job = { id: ++sequence, abort: new AbortController(), asPath: destination.pathname + destination.search + destination.hash, shallow: !!options.shallow };
     active = job;
+    const prefetchKey = new URL(request); prefetchKey.hash = '';
+    const releaseNavigation = scheduler.navigation(prefetches.get(prefetchKey.href)?.task);
+    job.abort.signal.addEventListener('abort', releaseNavigation, { once: true });
     const timer = setTimeout(() => job.abort.abort(new Error('Page navigation timed out')), 30_000);
     const hashOnly = destination.pathname === currentURL.pathname && destination.search === currentURL.search &&
       (destination.hash !== currentURL.hash || !!destination.hash) && !options.shallow;
@@ -458,7 +440,7 @@ export function createPagesNavigation({ initial, initialRoute, manifestUrl, read
       job.finished = true; active = undefined;
       events.emit('routeChangeError', error, job.asPath, { shallow: job.shallow });
       hard(destination, options.replace || options.pop); return false;
-    } finally { clearTimeout(timer); }
+    } finally { clearTimeout(timer); job.abort.signal.removeEventListener('abort', releaseNavigation); releaseNavigation(); }
   }
   async function reportRenderError(error, failedView) {
     if (failedView !== current && (failedView.clientSnapshot || failedView.Page !== current.Page || failedView.props !== current.props)) return false;
@@ -549,17 +531,25 @@ export function createPagesNavigation({ initial, initialRoute, manifestUrl, read
   };
   let frame;
   const onScroll = () => { if (frame !== undefined) return; frame = win.requestAnimationFrame(() => { frame = undefined; saveScroll(); }); };
-  const pagehide = () => { saveScroll(); active?.abort.abort(); renderingError?.abort.abort(); for (const key of prefetches.keys()) dropPrefetch(key); };
+  const pagehide = () => {
+    saveScroll(); cancelActive(); active = undefined;
+    renderingError?.abort.abort(); renderingError = undefined;
+    for (const key of prefetches.keys()) dropPrefetch(key);
+  };
   win.history.replaceState(historyState(currentURL, currentRequest, currentKey, {}, [win.scrollX, win.scrollY]), '', currentURL.href);
   win.history.scrollRestoration = 'manual';
   win.addEventListener('popstate', popstate); win.addEventListener('scroll', onScroll, { passive: true }); win.addEventListener('pagehide', pagehide);
   return { navigate, prefetch, saveScroll, reportRenderError, snapshot: () => current.router, beforePopState(callback) { beforePop = callback; },
+    ...(process.env.NODE_ENV === 'development' ? { devSetManifest(options) {
+      buildId=options.buildId;manifestUrl=options.manifestUrl;manifestPromise=undefined;
+      for(const key of prefetches.keys())dropPrefetch(key);
+    }} : {}),
     ...(process.env.NODE_ENV === 'development' ? { async devRefresh(options) {
       buildId = options.buildId; manifestUrl = options.manifestUrl; manifestPromise = undefined;
       for (const key of prefetches.keys()) dropPrefetch(key);
-      await navigate(currentRequest, currentURL, { replace: true, scroll: false });
+      await navigate(currentRequest, currentURL, { replace: true, scroll: false, devRefresh:true });
     } } : {}),
     refreshFallback,
-    dispose() { pagehide(); win.removeEventListener('popstate', popstate); win.removeEventListener('scroll', onScroll); win.removeEventListener('pagehide', pagehide); if (frame !== undefined) win.cancelAnimationFrame(frame); },
+    dispose() { pagehide(); scheduler.dispose(); win.removeEventListener('popstate', popstate); win.removeEventListener('scroll', onScroll); win.removeEventListener('pagehide', pagehide); if (frame !== undefined) win.cancelAnimationFrame(frame); },
   };
 }

package/runtime/persistent/client.mjs

@@ -19,13 +19,14 @@ export const persistentHelp = `Persistent apps (ordinary prn start stays in the
 pstart options: --name NAME --port 3000 --hostname 127.0.0.1 --workers 1
   --profile balanced|speed|memory|classic --inspect
   --health-path / --health-timeout 15000 --drain-timeout 30000 (milliseconds)
+  --rollback-window 15000 (post-switch monitoring; 0 disables, maximum 120000 ms)
 prestart/pstop/plogs default to the app in the current directory.
 plogs options: --lines 100 --follow. App environment comes from its .env files.
 State and logs: ~/.prnext/processes (override with PRNEXT_PM_HOME).
 `;
 
 export function parsePersistent(command, argv) {
-  const allowed = command === 'pstart' ? ['name', 'port', 'hostname', 'workers', 'profile', 'inspect', 'health-path', 'health-timeout', 'drain-timeout']
+  const allowed = command === 'pstart' ? ['name', 'port', 'hostname', 'workers', 'profile', 'inspect', 'health-path', 'health-timeout', 'drain-timeout', 'rollback-window']
     : command === 'plogs' ? ['follow', 'lines', 'supervisor'] : command === 'pstartup' ? ['remove']
     : ['pstatus', 'plist'].includes(command) ? ['json'] : ['prestart', 'pstop', 'pdelete'].includes(command) ? ['all'] : [];
   const flags = new Set(['inspect', 'follow', 'supervisor', 'remove', 'json', 'all']);
@@ -41,9 +42,9 @@ export function parsePersistent(command, argv) {
     } else { if (target !== undefined) throw new Error(`${command} accepts one ${command === 'pstart' ? 'directory' : 'app name'}`); target = arg; }
   }
   if (target && (options.all || options.supervisor || ['pstartup', 'pdown'].includes(command))) throw new Error('Choose an app name or a global option, not both.');
-  for (const key of ['port', 'workers', 'health-timeout', 'drain-timeout', 'lines']) if (key in options) {
-    const max = key === 'port' ? 65535 : key === 'workers' ? 64 : key === 'lines' ? 10000 : 60000;
-    const min = key.endsWith('timeout') ? 100 : 1;
+  for (const key of ['port', 'workers', 'health-timeout', 'drain-timeout', 'rollback-window', 'lines']) if (key in options) {
+    const max = key === 'port' ? 65535 : key === 'workers' ? 64 : key === 'lines' ? 10000 : key === 'rollback-window' ? 120000 : 60000;
+    const min = key === 'rollback-window' ? 0 : key.endsWith('timeout') ? 100 : 1;
     if (!/^\d+$/.test(options[key]) || Number(options[key]) < min || Number(options[key]) > max) throw new Error(`--${key} must be between ${min} and ${max}`);
     options[key] = Number(options[key]);
   }
@@ -156,7 +157,7 @@ export async function persistentCommand(command, argv) {
   if (command === 'pstart') {
     const root = await realpath(path.resolve(target || '.'));
     const name = validName(options.name || path.basename(root).replace(/[^a-zA-Z0-9_-]/g, '-').replace(/^[^a-zA-Z0-9]+/, '').slice(0, 64));
-    request = { command: 'start', config: { name, root, binary: await resolveNativeBinary(), node: process.execPath, port: options.port || 3000, hostname: options.hostname || '127.0.0.1', workers: options.workers || 1, profile: options.profile || process.env.PRNEXT_PROFILE || 'balanced', inspect: !!options.inspect, healthPath: options['health-path'] || '/', healthTimeout: options['health-timeout'] || 15000, drainTimeout: options['drain-timeout'] || 30000 } };
+    request = { command: 'start', config: { name, root, binary: await resolveNativeBinary(), node: process.execPath, port: options.port || 3000, hostname: options.hostname || '127.0.0.1', workers: options.workers || 1, profile: options.profile || process.env.PRNEXT_PROFILE || 'balanced', inspect: !!options.inspect, healthPath: options['health-path'] || '/', healthTimeout: options['health-timeout'] || 15000, drainTimeout: options['drain-timeout'] || 30000, rollbackWindow: options['rollback-window'] ?? 15000 } };
   } else request = { command: ({ prestart: 'restart', pstop: 'stop', pdelete: 'delete' })[command], name: target, all: !!options.all, root: target || options.all ? undefined : await realpath(process.cwd()) };
   await ensure(connection);
   const report = await rpc(connection, request);