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

package/compat/index.d.ts

@@ -13,6 +13,13 @@ export interface InstantSample {
 }
 export type InstantConfig = boolean | { level?: 'warning' | 'experimental-error'; unstable_samples?: InstantSample[]; unstable_disableValidation?: true; unstable_disableDevValidation?: true; unstable_disableBuildValidation?: true };
 
+export interface ReactCompilerOptions {
+  compilationMode?: 'infer' | 'annotation';
+  panicThreshold?: 'none' | 'critical_errors' | 'all_errors';
+  /** PRNext requires matching React 19 peers. */
+  target?: '19';
+}
+
 export type TurbopackCondition = 'browser' | 'foreign' | 'development' | 'production' | 'node' | 'edge-light'
   | {all: TurbopackCondition[]} | {any: TurbopackCondition[]} | {not: TurbopackCondition}
   | {path: string | RegExp; content?: RegExp} | {path?: string | RegExp; content: RegExp};
@@ -117,9 +124,17 @@ export interface NextConfig {
   /** PRNext only. CLI > environment > build configuration > profile.
    * 0 disables the corresponding retirement; keepWarm retains one lane per used host.
    */
+  /** Soft RSS retirement after three one-second samples; active work drains. */
+  workerMemory?: false | { maxRssMb: number };
   workerRetirement?: { idleSeconds?: number; laneIdleSeconds?: number; keepWarm?: boolean };
   /** Import selected Node routes on startup; top-level module code executes. RSS is a soft import budget. */
   workerPreload?: false | { routes: string[]; maxRssMb?: number; timeoutMs?: number };
+  /** Keep bounded previous public hashed assets. false disables carry-over. Defaults: one hour, two generations, 64 MiB. */
+  deploymentRetention?: false | {maxAge?: number; maxGenerations?: number; maxBytes?: number};
+  /** PRNext production prerender processes; maxMemoryMb bounds their combined observed memory. */
+  prerender?: {workers?: number; maxMemoryMb?: number};
+  /** Explicit App route patterns that must produce complete static HTML without browser JavaScript. */
+  htmlOnly?: string[];
   /** Bounded active development routes; default retains five requested routes. */
   onDemandEntries?: { maxInactiveAge?: number; pagesBufferLength?: number };
   /** PRNext development menu; bottom-left by default. false hides it without disabling errors or Fast Refresh. */
@@ -130,8 +145,8 @@ export interface NextConfig {
   images?: import('./image.cjs').ImageConfig;
   pageExtensions?: string[];
   reactStrictMode?: boolean;
-  /** Enabled React Compiler transforms are not implemented. */
-  reactCompiler?: false;
+  /** Opt in to the bundled official React Compiler for application components. Disabled by default. */
+  reactCompiler?: boolean | ReactCompilerOptions;
   /** Generate route completions and validate Link/router destinations. */
   typedRoutes?: boolean;
   /** Native CSS for default styles; custom PostCSS pipelines remain authoritative. */
@@ -139,6 +154,9 @@ export interface NextConfig {
   /** Production checks use the project's installed TypeScript without emitting files. */
   typescript?: { ignoreBuildErrors?: boolean; tsconfigPath?: string; devChecks?: boolean };
   cacheComponents?: boolean;
+  partialPrefetching?: boolean;
+  /** App Router inactive layout branches. Defaults to 4 entries for 120 seconds. */
+  navigationCache?: false | {maxEntries?: number; ttlMs?: number; authCookies?: readonly string[]};
   cacheLife?: Record<string, import('./cache.cjs').CacheLife>;
   transpilePackages?: string[];
   serverExternalPackages?: string[];
@@ -149,7 +167,7 @@ export interface NextConfig {
     implementation?: 'sass' | 'sass-embedded';
     [option: string]: unknown;
   };
-  experimental?: { nextScriptWorkers?: boolean; optimizePackageImports?: string[]; proxyClientMaxBodySize?: number | string; serverActions?: true | { allowedOrigins?: string[]; bodySizeLimit?: number | string } };
+  experimental?: { nextScriptWorkers?: boolean; /** App Router development only; compile literal client imports on first use. */ lazyDynamicImports?: boolean; optimizePackageImports?: string[]; proxyClientMaxBodySize?: number | string; serverActions?: true | { allowedOrigins?: string[]; bodySizeLimit?: number | string } };
   trailingSlash?: boolean;
   skipTrailingSlashRedirect?: boolean;
   skipMiddlewareUrlNormalize?: boolean;
@@ -196,7 +214,45 @@ export interface StaticBuildOptions {
   distDir?: string;
   dev?: false;
 }
-export interface BuildResult { buildId: string; outputDirectory: string; }
+export interface ReactCompilerReport {
+  version: 1;
+  compilerVersion: string | null;
+  enabled: boolean;
+  buildId: string | null;
+  mode: 'development' | 'production';
+  /** Incremental graphs can reuse inputs without observing their transforms. */
+  scope: 'observed-transforms';
+  options: boolean | ReactCompilerOptions | null;
+  truncated: boolean;
+  summary: {files: number; functions: number; optimized: number; skipped: number; errors: number; diagnostics: number; mixed: number; transforms: number; cacheReuses: number};
+  files: Array<{
+    file: string; transforms: number; cacheReuses: number; targets: string[]; notes: string[];
+    functions: Array<{
+      name: string | null;
+      start: {line: number; column: number} | null;
+      end: {line: number; column: number} | null;
+      status: 'optimized' | 'skipped' | 'error' | 'diagnostic' | 'mixed';
+      targets: string[];
+      events: Array<{
+        kind: 'CompileSuccess' | 'CompileSkip' | 'CompileError' | 'CompileDiagnostic' | 'PipelineError';
+        status: 'optimized' | 'skipped' | 'error' | 'diagnostic' | 'mixed';
+        reason: string | null; category: string | null; targets: string[]; policy?: boolean;
+        memoSlots?: number; memoBlocks?: number; memoValues?: number;
+      }>;
+    }>;
+  }>;
+  graphs: Array<{target: string; metadataAvailable: boolean; projectJavaScriptInputs: number; observedFiles: number; unobservedInputs: number}>;
+}
+export interface CompilationCacheReport {
+  version: 1;
+  scope: 'eligible-production-compilation-graphs';
+  hits: number;
+  misses: number;
+  bypasses: number;
+  reusedBytes: number;
+  kinds: Array<{kind: string; hits: number; misses: number; bypasses: number; writes: number; reusedBytes: number; reasons: Record<string, number>}>;
+}
+export interface BuildResult { buildId: string; outputDirectory: string; reactCompilerReport?: ReactCompilerReport; compilationCache?: CompilationCacheReport; }
 export interface ProductionBuilder {
   build(options?: {envMode?: 'production' | 'test'}): Promise<BuildResult>;
   stats(): {contexts: number; created: number; reused: number};
@@ -212,3 +268,12 @@ export function buildStatic(projectRoot: string, options?: StaticBuildOptions):
 export function readBuildOutput(buildDirectory: string): Promise<BuildOutput>;
 export function validateBuildOutput(value: unknown): BuildOutput;
 export type { DocumentContext, DocumentInitialProps, DocumentProps } from './document.cjs';
+
+/** Server instrumentation hooks, compatible with Next.js instrumentation files. */
+export namespace Instrumentation {
+  export type onRequestError = (error: unknown, request: Readonly<{path: string; method: string; headers: Record<string,string|string[]>}>, context: {
+    routerKind: 'App Router' | 'Pages Router'; routePath: string; routeType: 'render' | 'route' | 'action' | 'proxy';
+    renderSource: 'react-server-components' | 'react-server-components-payload' | 'server-rendering';
+    revalidateReason: 'on-demand' | 'stale' | undefined; renderType: 'dynamic' | 'dynamic-resume';
+  }) => void | Promise<void>;
+}

package/compat/link.cjs

@@ -7,7 +7,7 @@ const { addBasePath, hasBasePath, normalizeTrailingSlash } = require('./paths.cj
 const { localizedHref } = require('./locale.cjs');
 
 const Link = React.forwardRef(function Link({ href, as, children, replace, scroll, shallow, prefetch,
-  locale, legacyBehavior, passHref, onClick, onNavigate, onMouseEnter, onTouchStart, ...props }, ref) {
+  locale, legacyBehavior, passHref, onClick, onNavigate, onMouseEnter, onTouchStart, onFocus, ...props }, ref) {
   const app = React.useContext(AppRouterContext);
   const pages = React.useContext(RouterContext);
   const anchorRef = React.useRef(null);
@@ -19,14 +19,15 @@ const Link = React.forwardRef(function Link({ href, as, children, replace, scrol
     : target.startsWith('//') ? target : addBasePath(target, basePath);
   const publicTarget = normalizeTrailingSlash(mounted, policy);
   const source = formatUrl(href);
-  const requestPrefetch = React.useCallback(() => {
-    if (app?.router.partialPrefetch && prefetch !== false && process.env.NODE_ENV === 'production') app.router.prefetch(target);
-    if (!app && pages && process.env.NODE_ENV === 'production') void pages.prefetch(source, as ? target : undefined, {locale}).catch(() => {});
-  }, [app, pages, source, target, as, prefetch]);
+  const requestPrefetch = React.useCallback((priority = 'intent') => {
+    if (prefetch === false || process.env.NODE_ENV !== 'production') return;
+    if (app && (app.router.partialPrefetch || prefetch === true)) app.router.prefetch(target, { priority, full: prefetch === true });
+    if (!app && pages) void pages.prefetch(source, as ? target : undefined, { locale, priority }).catch(() => {});
+  }, [app, pages, source, target, as, locale, prefetch]);
   React.useEffect(() => {
-    if ((app ? !app.router.partialPrefetch : !pages) || prefetch === false || process.env.NODE_ENV !== 'production' || typeof IntersectionObserver === 'undefined' || !anchorRef.current) return;
+    if ((app ? !app.router.partialPrefetch && prefetch !== true : !pages) || prefetch === false || process.env.NODE_ENV !== 'production' || typeof IntersectionObserver === 'undefined' || !anchorRef.current) return;
     const observer = new IntersectionObserver(entries => {
-      if (entries.some(entry => entry.isIntersecting)) { observer.disconnect(); requestPrefetch(); }
+      if (entries.some(entry => entry.isIntersecting)) { observer.disconnect(); requestPrefetch('viewport'); }
     }, { rootMargin: '200px' });
     observer.observe(anchorRef.current);
     return () => observer.disconnect();
@@ -53,16 +54,18 @@ const Link = React.forwardRef(function Link({ href, as, children, replace, scrol
       void pages[replace ? 'replace' : 'push'](href, as, { scroll, shallow, locale }).catch(error => console.error(error));
     } else if (replace) { event.preventDefault(); window.location.replace(publicTarget); }
   }
-  function hover(event) { onMouseEnter?.(event); requestPrefetch(); }
-  function touch(event) { onTouchStart?.(event); requestPrefetch(); }
+  function hover(event) { onMouseEnter?.(event); if (!event.defaultPrevented) requestPrefetch(); }
+  function touch(event) { onTouchStart?.(event); if (!event.defaultPrevented) requestPrefetch(); }
+  function focus(event) { onFocus?.(event); if (!event.defaultPrevented) requestPrefetch(); }
   if (legacyBehavior) {
     const child = React.Children.only(children);
     return React.cloneElement(child, { ...props, href: publicTarget, ref: setRef,
       onMouseEnter(event) { child.props.onMouseEnter?.(event); hover(event); },
       onTouchStart(event) { child.props.onTouchStart?.(event); touch(event); },
+      onFocus(event) { child.props.onFocus?.(event); focus(event); },
       onClick(event) { child.props.onClick?.(event); if (!event.defaultPrevented) click(event); } });
   }
-  return React.createElement('a', { ...props, href: publicTarget, ref: setRef, onClick: click, onMouseEnter: hover, onTouchStart: touch }, children);
+  return React.createElement('a', { ...props, href: publicTarget, ref: setRef, onClick: click, onMouseEnter: hover, onTouchStart: touch, onFocus: focus }, children);
 });
 module.exports = Link;
 module.exports.default = Link;

package/compat/navigation-authorization.cjs

@@ -0,0 +1,9 @@
+'use strict';
+const { createHmac } = require('node:crypto');
+function navigationAuthorization(context, secret, cookieNames) {
+  if (!secret || context?.staticState) return undefined;
+  const names = cookieNames === undefined ? null : new Set(cookieNames);
+  const cookies = context.cookies.getAll().filter(cookie => !names || names.has(cookie.name)).map(({ name, value }) => [name, value]).sort((a, b) => a[0].localeCompare(b[0]));
+  return createHmac('sha256', secret).update(JSON.stringify([cookies, context.headers.get('authorization') || ''])).digest('hex');
+}
+module.exports = { navigationAuthorization };

package/compat/navigation-stages.cjs

@@ -0,0 +1,19 @@
+'use strict';
+const { optionalRequestContext, inCacheScope } = require('./data-cache.cjs');
+
+function postponeStage(name) {
+  throw Object.assign(new Error(`Deferred until ${name}.`), { code: 'PRNEXT_PPR_DYNAMIC', digest: 'PRNEXT_PPR_DYNAMIC' });
+}
+function stage(name) {
+  const context = optionalRequestContext();
+  if (!context?.cacheComponents) throw new Error(`${name}() requires cacheComponents: true.`);
+  if (inCacheScope()) throw new Error(`${name}() cannot run inside a cached function. Call it before invoking the cached function.`);
+  // Static prerenders deliberately continue through both gates. Cacheable work
+  // remains prerenderable and is not made request-dependent by either API.
+  if (context.staticState) return;
+  if (context.navigationStage === 'shell' && (name === 'navigation' || context.partialPrefetching)) postponeStage(name);
+  if (context.navigationStage === 'prefetch' && name === 'navigation') postponeStage(name);
+}
+async function navigation() { stage('navigation'); }
+async function prefetch() { stage('prefetch'); }
+module.exports = { navigation, prefetch, postponeStage };

package/compat/offline-store.cjs

@@ -0,0 +1,11 @@
+'use strict';
+const waiting=new Set(),listeners=new Set();
+const changed=()=>{for(const listener of listeners)listener();};
+const snapshot=()=>waiting.size>0||globalThis.navigator?.onLine===false;
+function subscribe(listener){
+  if(!listeners.size){globalThis.window?.addEventListener('online',changed);globalThis.window?.addEventListener('offline',changed);}
+  listeners.add(listener);
+  return()=>{listeners.delete(listener);if(!listeners.size){globalThis.window?.removeEventListener('online',changed);globalThis.window?.removeEventListener('offline',changed);}};
+}
+function beginWait(){const id={};waiting.add(id);changed();let ended=false;return()=>{if(ended)return;ended=true;waiting.delete(id);changed();};}
+module.exports={snapshot,subscribe,beginWait};

package/compat/offline.cjs

@@ -0,0 +1,5 @@
+'use client';
+'use strict';
+const React=require('react'),store=require('./offline-store.cjs');
+function useOffline(){return React.useSyncExternalStore(store.subscribe,store.snapshot,()=>false);}
+module.exports={useOffline};

package/compat/offline.d.cts

@@ -0,0 +1,2 @@
+/** True when the browser is offline or a navigation is waiting for connectivity. */
+export declare function useOffline(): boolean;

package/compat/redis-cache.cjs

@@ -0,0 +1,201 @@
+'use strict';
+const {createHash,randomBytes}=require('node:crypto');
+const MAX_VALUE=2*1024*1024,MAX_META=65536;
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const ACQUIRE=`
+if not redis.call('HGET',KEYS[2],'_incarnation') then redis.call('HSET',KEYS[2],'_incarnation',ARGV[3],'_epoch',ARGV[3]) end
+redis.call('PEXPIRE',KEYS[2],ARGV[4])
+local epoch=redis.call('HGET',KEYS[2],'_epoch');local incarnation=redis.call('HGET',KEYS[2],'_incarnation')
+if redis.call('SET',KEYS[1],ARGV[1],'NX','PX',ARGV[2]) then return {1,epoch,incarnation} end
+return {0}`;
+const RELEASE=`if redis.call('GET',KEYS[1])==ARGV[1] then return redis.call('DEL',KEYS[1]) end return 0`;
+const READ=`
+local fields=redis.call('HMGET',KEYS[1],'meta','value')
+if not fields[1] or not fields[2] or string.len(fields[1])>65536 or string.len(fields[2])>tonumber(ARGV[2]) then return nil end
+local meta=cjson.decode(fields[1]); local extra=cjson.decode(ARGV[1]); local stale=0
+if redis.call('HGET',KEYS[2],'_incarnation')~=meta.incarnation then return nil end
+local t=redis.call('TIME'); local now=tonumber(t[1])*1000+math.floor(tonumber(t[2])/1000)
+local seen={}
+for _,id in ipairs(meta.tagIds) do seen[id]=true end
+for _,id in ipairs(extra) do seen[id]=true end
+for id,_ in pairs(seen) do
+ local value=redis.call('HGET',KEYS[2],id)
+ if value then
+  local tag=cjson.decode(value)
+  if tag.generation~=(meta.versions[id] or '0') then
+   if tag.deadline>=0 and tag.deadline<=now then return nil end
+   stale=1
+  end
+ end
+end
+return {fields[1],fields[2],math.max(0,now-meta.storedAt),stale}`;
+const WRITE=`
+if redis.call('GET',KEYS[3])~=ARGV[1] or redis.call('HGET',KEYS[2],'_epoch')~=ARGV[2] then return 0 end
+local meta=cjson.decode(ARGV[3]); meta.versions={};meta.incarnation=ARGV[5];meta.writer=ARGV[1]
+local t=redis.call('TIME'); local now=tonumber(t[1])*1000+math.floor(tonumber(t[2])/1000)
+meta.storedAt=now-tonumber(ARGV[6])
+for _,id in ipairs(meta.tagIds) do
+ local value=redis.call('HGET',KEYS[2],id)
+ meta.versions[id]=value and cjson.decode(value).generation or '0'
+end
+local encoded=cjson.encode(meta)
+if string.len(encoded)>65536 then return 0 end
+redis.call('HSET',KEYS[1],'meta',encoded,'value',ARGV[4])
+redis.call('PEXPIRE',KEYS[1],ARGV[7]);redis.call('PEXPIRE',KEYS[2],ARGV[8]);return 1`;
+const INVALIDATE=`
+local generation=ARGV[3];local ids=cjson.decode(ARGV[4]);local added=0
+for _,id in ipairs(ids) do if redis.call('HEXISTS',KEYS[1],id)==0 then added=added+1 end end
+if redis.call('HLEN',KEYS[1])+added>4098 then redis.call('DEL',KEYS[1]) end
+if not redis.call('HGET',KEYS[1],'_incarnation') then redis.call('HSET',KEYS[1],'_incarnation',generation) end
+redis.call('HSET',KEYS[1],'_epoch',generation)
+local t=redis.call('TIME');local now=tonumber(t[1])*1000+math.floor(tonumber(t[2])/1000)
+local expiry=tonumber(ARGV[1]);local deadline=expiry<0 and -1 or now+expiry
+for _,id in ipairs(ids) do redis.call('HSET',KEYS[1],id,cjson.encode({generation=generation,deadline=deadline})) end
+redis.call('PEXPIRE',KEYS[1],ARGV[2])
+return 1`;
+const REMOVE=`local meta=redis.call('HGET',KEYS[1],'meta');if meta and cjson.decode(meta).writer==ARGV[1] then return redis.call('DEL',KEYS[1]) end return 0`;
+
+function tags(values=[]){
+  if(!Array.isArray(values)||values.length>256||values.some(value=>typeof value!=='string'||!value||Buffer.byteLength(value)>8192))throw new TypeError('Redis cache tags must be bounded nonempty strings.');
+  return [...new Set(values)];
+}
+function positive(value,fallback,min,max,name){value??=fallback;if(!Number.isSafeInteger(value)||value<min||value>max)throw new TypeError(`Redis cache ${name} must be between ${min} and ${max}.`);return value;}
+function pause(ms,signal){return new Promise((resolve,reject)=>{const done=error=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);error?reject(error):resolve();};const abort=()=>done(signal.reason);const timer=setTimeout(done,ms);signal?.addEventListener('abort',abort,{once:true});if(signal?.aborted)abort();});}
+function boundedRead(reader,ms){return new Promise((resolve,reject)=>{const timer=setTimeout(()=>reject(new Error('Redis cache value read timed out.')),ms);reader.read().then(value=>{clearTimeout(timer);resolve(value);},error=>{clearTimeout(timer);reject(error);});});}
+
+/** First-party Cache Components handler; Redis is loaded only when configured. */
+function createRedisCache(options={},maxValueBytes=MAX_VALUE){
+  if(!options||typeof options!=='object'||Array.isArray(options))throw new TypeError('Redis cache options must be an object.');
+  const known=new Set(['namespace','urlEnv','client','leaseMs','waitMs','commandTimeoutMs','maxAgeSeconds']);
+  for(const key of Object.keys(options))if(!known.has(key))throw new TypeError(`Unknown Redis cache option: ${key}`);
+  if(options.client!==undefined&&typeof options.client?.withTypeMapping!=='function')throw new TypeError('Redis cache client must be a node-redis client.');
+  if(typeof options.namespace!=='string'||!options.namespace||Buffer.byteLength(options.namespace)>256)throw new TypeError('Redis cache requires an application-specific namespace.');
+  const urlEnv=options.urlEnv??'REDIS_URL';if(typeof urlEnv!=='string'||!/^[_A-Za-z][_A-Za-z0-9]*$/.test(urlEnv))throw new TypeError('Redis cache urlEnv must name an environment variable.');
+  const leaseMs=positive(options.leaseMs,30000,1000,120000,'leaseMs'),waitMs=positive(options.waitMs,2500,100,3500,'waitMs');
+  const commandTimeoutMs=positive(options.commandTimeoutMs,1000,100,2000,'commandTimeoutMs'),maxAgeSeconds=positive(options.maxAgeSeconds,604800,1,2592000,'maxAgeSeconds');
+  if(waitMs+2*commandTimeoutMs>4500)throw new TypeError('Redis cache waitMs plus twice commandTimeoutMs must not exceed 4500 ms.');
+  const prefix='prnext:v1:{'+hash(options.namespace)+'}:',epochKey=prefix+'tags',retention=String(maxAgeSeconds*1000+leaseMs+60000);
+  let owned,connecting,closed=false;
+  async function client(){
+    if(closed)throw new Error('Redis cache is closed.');
+    if(options.client){
+      if(options.client.isReady===false)throw new Error('Redis cache client is not connected.');
+      return options.client;
+    }
+    if(owned?.isReady)return owned;
+    if(!connecting){
+      connecting=(async()=>{
+        const url=process.env[urlEnv];
+        if(!url||!/^rediss?:\/\//.test(url))throw new Error(`Set ${urlEnv} to a Redis connection URL.`);
+        // Use node-redis's base client; Redis Stack command packages are not
+        // needed by this provider's bounded EVAL/HASH protocol.
+        const {createClient}=require('@redis/client');
+        owned?.destroy();owned=createClient({url,disableOfflineQueue:true,commandsQueueMaxLength:128,socket:{connectTimeout:commandTimeoutMs,reconnectStrategy:false}});
+        owned.on('error',()=>{});await owned.connect();return owned;
+      })().finally(()=>{connecting=undefined;});
+    }
+    return connecting;
+  }
+  async function command(args,signal){
+    const connection=await client();
+    // '$' (36) is RESP's binary-safe bulk-string type, as exposed by node-redis.
+    const binary=connection.withTypeMapping({36:Buffer});
+    const deadline=AbortSignal.timeout(commandTimeoutMs);
+    return binary.sendCommand(args,{abortSignal:signal?AbortSignal.any([signal,deadline]):deadline});
+  }
+  const keys=key=>{if(typeof key!=='string'||!key||Buffer.byteLength(key)>8192)throw new TypeError('Invalid Redis cache key.');const id=hash(key);return {entry:prefix+'entry:'+id,lock:prefix+'lease:'+id};};
+  async function acquire(key,{signal}={}){
+    const {lock}=keys(key),token=randomBytes(24).toString('hex'),until=performance.now()+waitMs;
+    for(;;){
+      signal?.throwIfAborted();
+      const started=performance.now();
+      const result=await command(['EVAL',ACQUIRE,'2',lock,epochKey,token,String(leaseMs),randomBytes(24).toString('hex'),retention],signal);
+      if(Number(result[0])===1){let released=false;return {token,started,epoch:String(result[1]),incarnation:String(result[2]),async release(){if(released)return;released=true;await command(['EVAL',RELEASE,'1',lock,token]);}};}
+      if(performance.now()>=until)throw Object.assign(new Error('Redis cache fill wait exceeded its budget.'),{code:'PRNEXT_REDIS_BUSY'});
+      await pause(Math.min(50,Math.max(1,until-performance.now())),signal);
+    }
+  }
+  async function get(key,softTags=[]){
+    const result=await command(['EVAL',READ,'2',keys(key).entry,epochKey,JSON.stringify(tags(softTags).map(hash)),String(maxValueBytes)]);
+    if(!result)return undefined;
+    const meta=JSON.parse(result[0].toString('utf8')),bytes=result[1];
+    if(meta.version!==1||!Buffer.isBuffer(bytes)||bytes.length>maxValueBytes)throw new Error('Invalid Redis cache entry.');
+    const age=Number(result[2]);if(!Number.isFinite(age)||age<0)throw new Error('Invalid Redis cache age.');
+    let offset=0;
+    return {tags:meta.tags,stale:meta.stale,revalidate:Number(result[3])?0:meta.revalidate,expire:meta.expire,timestamp:Math.max(0,Date.now()-age),
+      value:new ReadableStream({pull(controller){if(offset===bytes.length){controller.close();return;}const end=Math.min(bytes.length,offset+65536);controller.enqueue(new Uint8Array(bytes.subarray(offset,end)));offset=end;}},{highWaterMark:0})};
+  }
+  async function set(key,pending,{lease,softTags=[]}={}){
+    if(!lease||!Number.isFinite(lease.started)){
+      // Observe and release a caller's value even when its lease is missing.
+      // An unfenced producer must never publish after an invalidation.
+      void Promise.resolve(pending).then(entry=>entry.value.cancel()).catch(()=>{});
+      throw new Error('Redis cache writes require the lease returned by acquire().');
+    }
+    const entry=await pending,entryTags=tags(entry.tags);
+    for(const field of ['timestamp','stale','revalidate','expire'])if(!Number.isFinite(entry[field])||entry[field]<0)throw new TypeError('Invalid Redis cache '+field);
+    const reader=entry.value.getReader(),chunks=[];let size=0,complete=false;
+    const until=performance.now()+commandTimeoutMs;
+    let reads=0;
+    try{for(;;){if(performance.now()>=until||++reads>10000)throw new Error('Redis cache value read timed out.');const part=await boundedRead(reader,Math.max(1,until-performance.now()));if(part.done){complete=true;break;}if(!(part.value instanceof Uint8Array)||(size+=part.value.byteLength)>maxValueBytes)throw new Error(`Redis cache value exceeds ${maxValueBytes/1024/1024} MiB.`);chunks.push(Buffer.from(part.value));}}
+    finally{if(!complete)void reader.cancel().catch(()=>{});reader.releaseLock();}
+    const meta={version:1,tags:entryTags,tagIds:tags([...entryTags,...softTags]).map(hash),stale:entry.stale,revalidate:entry.revalidate,expire:entry.expire};
+    const metadata=JSON.stringify(meta);if(Buffer.byteLength(metadata)>MAX_META)throw new Error('Redis cache metadata exceeds 64 KiB.');
+    const ttl=Math.ceil(Math.min(maxAgeSeconds,entry.expire)*1000);if(ttl<=0)return;
+    const {entry:entryKey,lock}=keys(key);
+    return Number(await command(['EVAL',WRITE,'3',entryKey,epochKey,lock,lease.token,lease.epoch,metadata,Buffer.concat(chunks,size),lease.incarnation,String(Math.max(0,performance.now()-lease.started)),String(ttl),retention]))===1;
+  }
+  async function updateTags(values,durations){
+    const list=tags(values);if(!list.length)return;
+    const expire=durations?.expire;if(expire!==undefined&&(!Number.isFinite(expire)||expire<0))throw new TypeError('Invalid Redis tag expiration.');
+    await command(['EVAL',INVALIDATE,'1',epochKey,String(expire===undefined?-1:Math.ceil(expire*1000)),retention,randomBytes(24).toString('hex'),JSON.stringify(list.map(hash))]);
+  }
+  return {get,set,acquire,updateTags,
+    async release(key,lease){if(lease?.token)await command(['EVAL',RELEASE,'1',keys(key).lock,lease.token]);},
+    async remove(key,lease){if(lease?.token)await command(['EVAL',REMOVE,'1',keys(key).entry,lease.token]);},
+    async refreshTags(){},async getExpiration(){return Infinity;},async close(){closed=true;await connecting?.catch(()=>{});if(owned?.isOpen)owned.destroy();}};
+}
+
+/** Legacy incremental handler for HTML/ISR, fetch and unstable_cache. */
+function createRedisIncrementalCache(options){
+  const {serialize,deserialize}=require('node:v8');
+  const backend=createRedisCache({leaseMs:60000,...options},16*1024*1024);
+  const keyFor=key=>'incremental:v8-'+process.versions.v8.split('.')[0]+':'+key;
+  function leaseFor(lease){
+    if(!lease||!['token','epoch','incarnation'].every(field=>typeof lease[field]==='string'&&/^[a-f0-9]{48}$/.test(lease[field]))||!Number.isFinite(lease.startedAt))throw new Error('Incremental Redis writes require a valid generation lease.');
+    return {...lease,started:performance.now()-Math.max(0,Date.now()-lease.startedAt)};
+  }
+  return class RedisIncrementalCache {
+    get prnextLeaseVersion(){return 1;}
+    async acquire(key,{signal}={}){
+      const lease=await backend.acquire(keyFor(key),{signal});
+      return {token:lease.token,epoch:lease.epoch,incarnation:lease.incarnation,startedAt:Date.now()};
+    }
+    async release(key,lease){await backend.release(keyFor(key),lease);}
+    async get(key,context={}){
+      const entry=await backend.get(keyFor(key),tags([...new Set([...(context.tags||[]),...(context.softTags||[])])]));
+      if(!entry)return null;
+      const bytes=Buffer.from(await new Response(entry.value).arrayBuffer());
+      const payload=deserialize(bytes);
+      if(payload?.version!==1||!Number.isFinite(payload.lastModified)||!payload.value||typeof payload.value.kind!=='string')throw new Error('Invalid incremental Redis payload.');
+      return {value:payload.value,lastModified:payload.lastModified,isStale:entry.revalidate===0};
+    }
+    async set(key,value,context={}){
+      const lease=leaseFor(context.prnextLease);
+      if(value===null){await backend.remove(keyFor(key),lease);return true;}
+      const raw=context.cacheControl?.revalidate??value.revalidate??value._prnext?.revalidate??false;
+      if(raw!==false&&(!Number.isFinite(raw)||raw<0))throw new TypeError('Invalid incremental Redis revalidate value.');
+      if(raw===0)return true;
+      const revalidate=raw===false?31536000:raw;
+      const entryTags=tags([...new Set([...(context.tags||[]),...(context.softTags||[])])]);
+      const bytes=serialize({version:1,lastModified:Date.now(),value});
+      if(bytes.length>16*1024*1024)throw new Error('Incremental Redis entry exceeds 16 MiB.');
+      return backend.set(keyFor(key),Promise.resolve({timestamp:Date.now(),stale:0,revalidate,expire:Math.max(revalidate,options?.maxAgeSeconds??604800),tags:entryTags,
+        value:new ReadableStream({start(controller){controller.enqueue(bytes);controller.close();}})}),{lease});
+    }
+    async revalidateTag(values,durations){await backend.updateTags(Array.isArray(values)?values:[values],durations);}
+    resetRequestCache(){}
+    async close(){await backend.close();}
+  };
+}
+module.exports={createRedisCache,createRedisIncrementalCache};

package/compat/redis-cache.d.cts

@@ -0,0 +1,37 @@
+/// <reference types="node" />
+export interface RedisCacheOptions {
+  /** Unique application namespace, shared by its replicas. */
+  namespace: string;
+  /** Runtime environment variable; the URL is never embedded in a build. Default REDIS_URL. */
+  urlEnv?: string;
+  /** An already-connected node-redis client. Its lifecycle remains yours. */
+  client?: {readonly isReady?: boolean; withTypeMapping(mapping: {36: BufferConstructor}): {sendCommand(args: (string | Buffer)[], options?: {abortSignal?: AbortSignal}): Promise<unknown>}};
+  leaseMs?: number;
+  waitMs?: number;
+  commandTimeoutMs?: number;
+  maxAgeSeconds?: number;
+}
+interface CacheEntry {value: ReadableStream<Uint8Array>; tags: string[]; timestamp: number; stale: number; revalidate: number; expire: number}
+interface Lease {token: string; started: number; epoch: string; incarnation: string; release(): Promise<void>}
+export declare function createRedisCache(options: RedisCacheOptions): {
+  get(key: string, softTags?: string[]): Promise<CacheEntry | undefined>;
+  set(key: string, entry: Promise<CacheEntry>, options?: {lease?: Lease; softTags?: string[]}): Promise<void>;
+  acquire(key: string, options?: {signal?: AbortSignal}): Promise<Lease>;
+  refreshTags(): Promise<void>;
+  getExpiration(): Promise<number>;
+  updateTags(tags: string[], durations?: {expire: number}): Promise<void>;
+  close(): Promise<void>;
+};
+
+export interface IncrementalRedisLease {token: string; epoch: string; incarnation: string; startedAt: number}
+/** Configure its returned constructor as cacheHandler; Cache Components use createRedisCache separately. */
+export declare function createRedisIncrementalCache(options: RedisCacheOptions): new (context?: unknown) => {
+  readonly prnextLeaseVersion: 1;
+  acquire(key: string, options?: {signal?: AbortSignal}): Promise<IncrementalRedisLease>;
+  release(key: string, lease: IncrementalRedisLease): Promise<void>;
+  get(key: string, context?: {tags?: string[]; softTags?: string[]}): Promise<{value: unknown; lastModified: number; isStale?: boolean} | null>;
+  set(key: string, value: unknown, context?: {prnextLease?: IncrementalRedisLease; tags?: string[]; softTags?: string[]; cacheControl?: {revalidate: number | false}}): Promise<boolean>;
+  revalidateTag(tags: string | string[], durations?: {expire?: number}): Promise<void>;
+  resetRequestCache(): void;
+  close(): Promise<void>;
+};

package/compat/server-primitives.cjs

@@ -1,5 +1,5 @@
 'use strict';
-const { CookieStore, ResponseCookieStore } = require('./cookies.cjs');
+const { RequestCookieStore, ResponseCookieStore } = require('./cookies.cjs');
 const { hasBasePath, addBasePath, removeBasePath } = require('./paths.cjs');
 const { localePath, withLocale } = require('./locale.cjs');
 
@@ -14,21 +14,37 @@ function middlewareHeaders(init, headers) {
   headers.set('x-middleware-override-headers', names.join(','));
 }
 
+function nextDataPath(pathname) {
+  const match = /^\/_next\/data\/([^/]+)\/(.*)\.json$/.exec(pathname);
+  if (!match) return { pathname };
+  const parts = match[2].split('/');
+  return { buildId: match[1], pathname: parts[0] === 'index' ? '/' : '/' + parts.join('/') };
+}
+
 class NextURL extends URL {
   constructor(input, baseOrOptions, options) {
     const base = typeof baseOrOptions === 'string' || baseOrOptions instanceof URL ? baseOrOptions : undefined;
     const config = options || (base ? {} : baseOrOptions) || {};
     super(input, base || config.base);
     this._nextConfig = config.nextConfig || {};
+    this._forceLocale = config.forceLocale === true;
+    this._parseData = !(this._nextConfig.skipProxyUrlNormalize ?? this._nextConfig.skipMiddlewareUrlNormalize);
     this._trailingSlash = super.pathname === '/' ? !!this._nextConfig.trailingSlash : super.pathname.endsWith('/');
     this._basePath = hasBasePath(super.pathname, this._nextConfig.basePath) ? this._nextConfig.basePath || '' : '';
-    this._locale = this._nextConfig.i18n ? localePath(removeBasePath(super.pathname, this._basePath), {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
+    const logical = this._parseData ? nextDataPath(removeBasePath(super.pathname, this._basePath)) : { pathname: removeBasePath(super.pathname, this._basePath) };
+    this._buildId = logical.buildId;
+    this._locale = this._nextConfig.i18n ? localePath(logical.pathname, {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
+  }
+  get pathname() {
+    const raw = removeBasePath(super.pathname, this._basePath);
+    return localePath(this._parseData ? nextDataPath(raw).pathname : raw, this._nextConfig.i18n).pathname;
   }
-  get pathname() { return localePath(removeBasePath(super.pathname, this._basePath), this._nextConfig.i18n).pathname; }
   set pathname(value) { super.pathname = addBasePath(withLocale(String(value).startsWith('/') ? value : `/${value}`, this._locale, this.defaultLocale), this._basePath); }
   get defaultLocale() { return this.domainLocale?.defaultLocale || this._nextConfig.i18n?.defaultLocale; }
   get domainLocale() { return this._nextConfig.i18n?.domains?.find(value=>value.domain.toLowerCase()===this.host.toLowerCase()); }
   get locale() { return this._locale; }
+  get buildId() { return this._buildId; }
+  set buildId(value) { this._buildId = value; }
   set locale(value) {
     if (!this._nextConfig.i18n?.locales.includes(value)) throw new TypeError(`Unknown locale: ${value}`);
     const pathname=this.pathname;this._locale=value;this.pathname=pathname;
@@ -43,8 +59,13 @@ class NextURL extends URL {
   set trailingSlash(value) { this._trailingSlash = value; }
   get href() {
     const url = new URL(super.href);
-    if (this._nextConfig.i18n) url.pathname=addBasePath(withLocale(this.pathname,this._locale,this.defaultLocale),this._basePath);
-    if (this._trailingSlash) { if (!url.pathname.endsWith('/')) url.pathname += '/'; }
+    let pathname = withLocale(this.pathname, this._locale, this._buildId || this._forceLocale ? undefined : this.defaultLocale);
+    if (this._buildId) {
+      pathname = pathname.replace(/\/$/, '');
+      pathname = '/_next/data/' + this._buildId + pathname + (this.pathname === '/' ? '/index.json' : '.json');
+    }
+    url.pathname = addBasePath(pathname, this._basePath);
+    if (this._trailingSlash && !this._buildId) { if (!url.pathname.endsWith('/')) url.pathname += '/'; }
     else if (url.pathname !== '/') url.pathname = url.pathname.replace(/\/$/, '');
     return url.href;
   }
@@ -54,19 +75,18 @@ class NextURL extends URL {
     super.href = value;
     this._trailingSlash = super.pathname === '/' ? !!this._nextConfig.trailingSlash : super.pathname.endsWith('/');
     this._basePath = hasBasePath(super.pathname, this._nextConfig.basePath) ? this._nextConfig.basePath || '' : '';
-    this._locale = this._nextConfig.i18n ? localePath(removeBasePath(super.pathname, this._basePath), {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
+    const logical = this._parseData ? nextDataPath(removeBasePath(super.pathname, this._basePath)) : { pathname: removeBasePath(super.pathname, this._basePath) };
+    this._buildId = logical.buildId;
+    this._locale = this._nextConfig.i18n ? localePath(logical.pathname, {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
   }
-  clone() { return new NextURL(this.href, { nextConfig: this._nextConfig }); }
+  clone() { return new NextURL(this.href, { nextConfig: this._nextConfig, forceLocale: this._forceLocale }); }
 }
 
 class NextRequest extends Request {
   constructor(input, init) {
     super(input, init);
     this.nextUrl = new NextURL(this.url, { nextConfig: init?.nextConfig || input?.nextUrl?._nextConfig });
-    this.cookies = new CookieStore(this.headers.get('cookie') || '', {
-      mutable: true,
-      onChange: () => this.headers.set('cookie', this.cookies.toString()),
-    });
+    this.cookies = new RequestCookieStore(this.headers);
   }
 }
 

package/compat/server.d.cts

@@ -1,7 +1,20 @@
 import type { CookieStore } from './headers.cjs';
 export interface NextURLConfig { i18n?: import('./index.js').NextConfig['i18n']; basePath?: string; trailingSlash?: boolean; skipMiddlewareUrlNormalize?: boolean; skipProxyUrlNormalize?: boolean }
-export class NextURL extends URL { constructor(input: string | URL, options?: { base?: string | URL; nextConfig?: NextURLConfig }); constructor(input: string | URL, base: string | URL, options?: { nextConfig?: NextURLConfig }); clone(): NextURL; locale: string; readonly defaultLocale?: string; readonly domainLocale?: NonNullable<NonNullable<import('./index.js').NextConfig['i18n']>['domains']>[number]; basePath: string; trailingSlash: boolean }
-export class NextRequest extends Request { constructor(input: RequestInfo | URL, init?: RequestInit & { nextConfig?: NextURLConfig }); nextUrl: NextURL; cookies: CookieStore }
+export class NextURL extends URL { constructor(input: string | URL, options?: { base?: string | URL; nextConfig?: NextURLConfig; forceLocale?: boolean }); constructor(input: string | URL, base: string | URL, options?: { nextConfig?: NextURLConfig; forceLocale?: boolean }); clone(): NextURL; buildId: string | undefined; locale: string; readonly defaultLocale?: string; readonly domainLocale?: NonNullable<NonNullable<import('./index.js').NextConfig['i18n']>['domains']>[number]; basePath: string; trailingSlash: boolean }
+export interface RequestCookie { name: string; value: string }
+export interface RequestCookieStore extends Iterable<[string, RequestCookie]> {
+  readonly size: number;
+  get(name: string | {name: string}): RequestCookie | undefined;
+  getAll(name?: string | {name: string}): RequestCookie[];
+  has(name: string): boolean;
+  set(name: string, value: string): this;
+  set(cookie: RequestCookie): this;
+  delete(name: string): boolean;
+  delete(names: string[]): boolean[];
+  clear(): this;
+  toString(): string;
+}
+export class NextRequest extends Request { constructor(input: RequestInfo | URL, init?: RequestInit & { nextConfig?: NextURLConfig }); nextUrl: NextURL; cookies: RequestCookieStore }
 export interface MiddlewareResponseInit extends ResponseInit { request?: { headers?: Headers } }
 export class NextResponse<Body = unknown> extends Response {
   cookies: CookieStore;

package/compat/static-generation.cjs

@@ -27,6 +27,13 @@ function dynamicUsage(reason, request = context()) {
 function staticBailout(reason, request = context()) {
   if (diagnostics.enabled) diagnostics.record('dynamic', { route: diagnostics.route(request), reason });
   const state = request?.staticState;
+  if (!state && request?.navigationStage && ['an uncached fetch', 'connection()', 'unstable_noStore()'].includes(reason)
+      && !require('./data-cache.cjs').inCacheScope()) require('./navigation-stages.cjs').postponeStage(reason);
+  const requirement = request?.cacheConfig?.ensureStatic;
+  if (!state && (request?.navigationStage === 'shell' && ['shell', 'prefetch', 'navigation'].includes(requirement)
+      || request?.navigationStage === 'prefetch' && ['prefetch', 'navigation'].includes(requirement))) {
+    require('./navigation-stages.cjs').postponeStage(reason);
+  }
   if (!state) return true;
   if (state.partial && state.mode === 'auto') {
     state.dynamicReasons.add(reason);

package/compat/use-cache.cjs

@@ -35,6 +35,9 @@ function recordCacheDependency({ tags = [], revalidate } = {}) {
 }
 function metadata(scope, context) { return { ...scope.life, revalidate: Math.min(scope.life.revalidate, scope.life.expire), tags: [...scope.tags], paths: getCachePaths(context), ...(scope.externalCache ? { externalCache: true } : {}) }; }
 function propagate(info, parent, context) {
+  if (context?.staticState && context.cacheConfig?.ensureStatic === 'navigation' && (info.expire < 300 || info.stale < 30 || info.revalidate === 0)) {
+    dynamicUsage('a cache lifetime with expire below 300 seconds, stale below 30 seconds, or revalidate=0', context);
+  }
   trackStaticDependency(info, context);
   if (!parent || parent === true) return;
   if (info.externalCache) parent.externalCache = true;