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

package/runtime/app-render.mjs

@@ -1,7 +1,8 @@
 import {reportRequestError,acknowledgeRequestError} from './instrumentation.mjs';
 import {currentTraceparent} from './trace.mjs';
 import React from 'react';
-import { randomUUID, createHmac, randomBytes } from 'node:crypto';
+import { randomUUID, createHmac } from 'node:crypto';
+import { developmentNavigationSecret } from '../compat/navigation-authorization.cjs';
 import diagnostics from '../compat/diagnostics.cjs';
 import { rscResourceLimits } from './profile.mjs';
 import { fontPreloads } from './font-preload.mjs';
@@ -14,7 +15,7 @@ import { workerMetadata, freezeClientModules, isImmutableClientModules } from '.
 import { workerArtifacts } from './worker-artifacts.mjs';
 import path from 'node:path';
 import { PARTIAL_PREFETCH_TYPE, PARTIAL_PREFETCH_BYTES } from './app-prefetch.mjs';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { AppRouterProvider } from '../compat/app-context.cjs';
 import { appContent } from './app-content.mjs';
@@ -28,6 +29,7 @@ import { installFetchCache } from './fetch-cache.mjs';
 import { partialArtifact, partialShell } from './app-partial.mjs';
 import { partialKeyMap } from './app-partial-model.mjs';
 import { partialIdentity } from './partial-artifact-cache.mjs';
+import {nativePprArtifact} from './native-ppr.mjs';
 import { isDraftRequest } from '../compat/draft.cjs';
 import { createRscLifecycle } from './rsc-lifecycle.mjs';
 import { trackRequestWork } from './request-work.mjs';
@@ -43,7 +45,6 @@ const metadata = new WeakMap();
 const artifacts = new WeakMap();
 const edgeManifests = new WeakMap();
 const emptyManifest = Object.freeze({});
-const developmentAuthorizationSecret = randomBytes(32).toString('hex');
 let nextId = 0;
 const pending = new Map();
 const noop = () => {};
@@ -242,19 +243,44 @@ function getWorker(production) {
   return current;
 }
 export async function prewarmAppRenderer(options){
+  if(!Number.isFinite(options?.timeoutMs)||options.timeoutMs<=0||options.timeoutMs>30000||!Number.isFinite(options?.maxRssMb)||options.maxRssMb<=0||options.maxRssMb>2048)throw new TypeError('Invalid renderer prewarm budget');
+  const deadline=performance.now()+options.timeoutMs;
+  const remaining=()=>{
+    options.signal?.throwIfAborted();
+    if(performance.now()>=deadline||process.memoryUsage().rss>=options.maxRssMb*1024*1024)throw new Error('Renderer prewarm budget exhausted');
+    return Math.max(1,deadline-performance.now());
+  };
+  remaining();
   flightDecoder(true);
-  await preloadAppRoutes([],options);
+  // The progressive HTML renderer is otherwise imported by the first document
+  // request. This prepares framework code only, never an application route.
+  htmlRuntime ??= await import('./app-stream-html.mjs');
+  const flight=await preloadAppRoutes([],{maxRssMb:options.maxRssMb,timeoutMs:remaining(),signal:options.signal,frameworkWarmup:true});
+  remaining();
+  if(!(flight instanceof ArrayBuffer)||flight.byteLength>65536)throw new Error('Invalid renderer prewarm Flight');
+  const body=new ReadableStream({start(controller){controller.enqueue(new Uint8Array(flight));controller.close();}});
+  let response,htmlBytes=0;
+  try{
+    response=await htmlRuntime.renderProgressiveAppHtml({result:{body,status:200},request:{production:true,method:'GET',clientModules:{},distDir:path.dirname(fileURLToPath(import.meta.url)),strictMode:true},route:{},responseHeaders:{},decodeFlight,signal:options.signal,timeoutMs:remaining()});
+    for await(const chunk of response.body){remaining();htmlBytes+=chunk.byteLength;if(htmlBytes>65536)throw new Error('Renderer prewarm HTML exceeds its byte budget');}
+    remaining();
+    return{flightBytes:flight.byteLength,htmlBytes,synthetic:true};
+  }finally{await response?.cancel();}
 }
 export async function preloadAppRoutes(files,options){
+  const {signal,...wireOptions}=options;
+  signal?.throwIfAborted();
   const worker=getWorker(true),id=`preload-${++nextId}`;
   worker.ref();
-  try{await new Promise((resolve,reject)=>{
-    const clean=()=>{clearTimeout(timer);worker.off('message',message);worker.off('error',error);worker.off('exit',exit);};
-    const message=value=>{if(value.type==='preloaded'&&value.id===id){clean();value.error?reject(new Error(value.error)):resolve();}};
+  try{return await new Promise((resolve,reject)=>{
+    const clean=()=>{clearTimeout(timer);worker.off('message',message);worker.off('error',error);worker.off('exit',exit);signal?.removeEventListener('abort',cancel);};
+    const message=value=>{if(value.type==='preloaded'&&value.id===id){clean();value.error?reject(new Error(value.error)):resolve(value.frameworkFlight);}};
     const error=value=>{clean();reject(value);};const exit=()=>error(new Error('RSC worker exited while preloading'));
+    const cancel=()=>{try{worker.postMessage({type:'preload-cancel',id});}catch{}finally{error(signal.reason);}};
     const timer=setTimeout(()=>{clean();void lifecycles.get(worker)?.terminate(new Error('RSC preload timed out'));reject(new Error('RSC preload timed out'));},options.timeoutMs);
     worker.on('message',message);worker.once('error',error);worker.once('exit',exit);
-    worker.postMessage({type:'preload',id,value:{files,options}});
+    signal?.addEventListener('abort',cancel,{once:true});
+    try{worker.postMessage({type:'preload',id,value:{files,options:wireOptions}});}catch(failure){error(failure);}
   });}finally{if(!hasPending(worker)&&!lifecycles.get(worker)?.retiring)worker.unref();}
 }
 
@@ -506,7 +532,7 @@ export async function renderAppPage(options) {
   return differentialFlight(response, options);
 }
 
-async function renderAppPageInner({ modulePath, route = {}, manifest = {}, distDir = path.dirname(path.dirname(modulePath)), url = 'http://localhost/', originalUrl, params = {}, method = 'GET', headers = {}, routingRequestHeaders, routingResolver, body = '', production = process.env.NODE_ENV === 'production', stream = false, signal, deferFinalizer }) {
+async function renderAppPageInner({ modulePath, route = {}, manifest = {}, distDir = path.dirname(path.dirname(modulePath)), url = 'http://localhost/', originalUrl, params = {}, method = 'GET', headers = {}, routingRequestHeaders, routingResolver, body = '', production = process.env.NODE_ENV === 'production', stream = false, signal, deferFinalizer, renderMode }) {
   if (route.htmlOnly) return { status:409, headers:{'content-type':'text/plain; charset=utf-8','cache-control':'private, no-store','x-prnext-document-navigation':'1'}, body:Buffer.from('This HTML-only page requires its prerendered document.') };
   let clientModules = manifest.app?.clientModules || emptyManifest;
   if (route.cacheConfig?.runtime === 'edge') {
@@ -522,7 +548,7 @@ async function renderAppPageInner({ modulePath, route = {}, manifest = {}, distD
   }
   const responseHeaders = { 'cache-control': 'private, no-cache, no-store, max-age=0', vary: 'RSC' };
   const request = { modulePath, routePattern: route.pattern, cacheConfig: route.cacheConfig, css: route.css || [], cssScopes: route.cssScopes || [], fonts: route.fonts || [], nonce: scriptNonce(headers), basePath: manifest.config?.basePath || '', trailingSlash: manifest?.config?.trailingSlash || false, skipTrailingSlashRedirect: manifest?.config?.skipTrailingSlashRedirect || false, url, originalUrl, params, method, headers, clientModules, production,
-    distDir, traceparent:currentTraceparent(), instrumentation:manifest.instrumentation, strictMode: manifest.config?.reactStrictMode !== false, cacheComponents: manifest.config?.cacheComponents, navigationCache: manifest.config?.navigationCache, authorizationSecret: production ? manifest.app?.actionKey : developmentAuthorizationSecret, partialPrefetching: manifest.config?.partialPrefetching, cacheLife: manifest.config?.cacheLife, cacheHandlers: manifest.config?.cacheHandlers, cacheHandler: manifest.config?.cacheHandler, cacheMaxMemorySize: manifest.config?.cacheMaxMemorySize, serverActions: manifest.config?.serverActions, previewModeId: manifest.previewModeId, actions: manifest.app?.actions || emptyManifest, actionKey: manifest.app?.actionKey };
+    distDir, traceparent:currentTraceparent(), instrumentation:manifest.instrumentation, strictMode: manifest.config?.reactStrictMode !== false, cacheComponents: manifest.config?.cacheComponents, navigationCache: manifest.config?.navigationCache, authorizationSecret: production ? manifest.app?.actionKey : developmentNavigationSecret(manifest.app?.actionKey), partialPrefetching: manifest.config?.partialPrefetching, cacheLife: manifest.config?.cacheLife, cacheHandlers: manifest.config?.cacheHandlers, cacheHandler: manifest.config?.cacheHandler, cacheMaxMemorySize: manifest.config?.cacheMaxMemorySize, serverActions: manifest.config?.serverActions, previewModeId: manifest.previewModeId, actions: manifest.app?.actions || emptyManifest, actionKey: manifest.app?.actionKey };
   if (route.parallel) {
     request.routingResolver = routingResolver;
     request.skipProxyUrlNormalize = manifest.config?.skipProxyUrlNormalize;
@@ -554,6 +580,8 @@ async function renderAppPageInner({ modulePath, route = {}, manifest = {}, distD
     }
   }
   const header = name => Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
+  const native = await nativePprArtifact({renderMode, manifest, route, url, distDir});
+  if (native) request.nativePpr = native.descriptor;
   if (request.partialPrefetching && manifest.app?.actionKey) {
     // Preview identity includes authorization, but exposes no cookie material or
     // guessable credential hash. A changed login cannot reveal an old preview.
@@ -591,7 +619,7 @@ async function renderAppPageInner({ modulePath, route = {}, manifest = {}, distD
     const generic = route.pprGeneric?.find(item => Object.entries(item.params).every(([name, value]) => JSON.stringify(params[name]) === JSON.stringify(value)));
     const filename = (!originalUrl ? route.ppr?.[pathname] : undefined) || generic?.file;
     if (filename || route.pprFallback) {
-      const artifact = await partialArtifact({ request, route, manifest, filename, identity: filename === generic?.file ? filename : `${pathname}:${originalUrl ? new URL(originalUrl).pathname : ''}`, signal,
+      const artifact = native?.artifact || await partialArtifact({ request, route, manifest, filename, identity: filename === generic?.file ? filename : `${pathname}:${originalUrl ? new URL(originalUrl).pathname : ''}`, signal,
         regenerate: async build => (await import('./app-static.mjs')).prerenderAppRoute({ modulePath, route, manifest, distDir, production, renderMode:'isr',
           path: build?.generic?.path || pathname, originalUrl: build?.generic ? undefined : originalUrl,
           params: build?.generic?.params || params, partialParams: build?.generic?.unknown }),
@@ -672,6 +700,7 @@ async function renderPartialAppPage({ request, route, artifact, responseHeaders,
   const keys = [...partialKeyMap(artifact.keyScopes, request.params, removeBasePath(new URL(request.url).pathname, request.basePath))];
   const partialRequest = { ...request, partialFlight: artifact.flight, ...(keys.length ? { partialKeys: keys } : {}) };
   const headers = { ...artifact.headers, ...responseHeaders, 'x-prnext-prerender': artifact.complete ? 'complete' : 'partial', 'content-type': rsc ? 'text/x-component; charset=utf-8' : 'text/html; charset=utf-8' };
+  if (request.nativePpr) headers['x-prnext-native-ppr'] = request.nativePpr.artifactHash;
   const identity = partialIdentity(artifact);
   headers['x-prnext-ppr-id'] = identity;
   if (prefetch) {
@@ -703,7 +732,7 @@ async function renderPartialAppPage({ request, route, artifact, responseHeaders,
   let rendered;
   const cancel = async reason => { abort.abort(reason || new Error('Partial response cancelled')); await rendered?.cancel?.(reason); };
   const body = (async function* () {
-    let sent = 0;
+    let sent = request.nativePpr ? Buffer.byteLength(shell.replace(/<\/body><\/html>$/i, '')) : 0;
     const bounded = chunk => {
       sent += chunk.byteLength;
       if (sent > MAX_RESPONSE_BYTES) throw new Error('Response exceeds the 16 MiB PRNext limit');
@@ -712,7 +741,7 @@ async function renderPartialAppPage({ request, route, artifact, responseHeaders,
     try {
       // The committed bytes come straight from prerender. Even a blocked
       // request component cannot hold back this shared document shell.
-      yield bounded(Buffer.from(shell.replace(/<\/body><\/html>$/i, '')));
+      if (!request.nativePpr) yield bounded(Buffer.from(shell.replace(/<\/body><\/html>$/i, '')));
       const result = await continueFlight(combinedSignal, true);
       rendered = await renderProgressiveAppHtml({ result, request, route, responseHeaders, decodeFlight, signal: combinedSignal,
         partial: { shell, postponed: artifact.postponed, shellSent: true, resumeKeys: keys.map(([from, to]) => [to, from]) } });

package/runtime/app-stream-channel.mjs

@@ -1,5 +1,6 @@
 // One initial transferable chunk, then one chunk per reader pull. The initial
 // credit removes a round trip while keeping the queue bounded to 64 KiB.
+import { ownFlightStream } from '../compat/flight-delta.cjs';
 export const APP_STREAM_CHUNK_BYTES = 64 * 1024;
 
 export function workerStreamChannel(port, id) {
@@ -11,6 +12,8 @@ export function workerStreamChannel(port, id) {
   let ended = false;
   let previousSignal;
   let combinedSignal;
+  let chunkMessage;
+  let transfer;
   const wait = async signal => {
     while (!credit) {
       signal.throwIfAborted();
@@ -42,11 +45,22 @@ export function workerStreamChannel(port, id) {
         if (!Buffer.isBuffer(bytes) && offset === 0 && length === bytes.byteLength && bytes.buffer.byteLength <= APP_STREAM_CHUNK_BYTES) chunk = bytes;
         else { chunk = new Uint8Array(length); chunk.set(bytes.subarray(offset, offset + length)); }
         const last = offset + length === bytes.byteLength;
-        const message = { id, type: metadata ? 'start' : 'chunk', ...metadata,
-          chunk: chunk.buffer, byteOffset: chunk.byteOffset, byteLength: chunk.byteLength, done: done && last };
+        // MessagePort serializes synchronously. Reuse this request's ordinary
+        // chunk envelope and transfer list after the first frame rather than
+        // allocating both for every chunk. The one-frame case keeps its old
+        // allocation count; no envelope or payload is shared across requests.
+        const message = metadata ? { id, type: 'start', ...metadata }
+          : chunkMessage ??= { id, type: 'chunk' };
+        const complete = done && last;
+        message.chunk = chunk.buffer;
+        message.byteOffset = chunk.byteOffset;
+        message.byteLength = chunk.byteLength;
+        message.done = complete;
         metadata = undefined;
-        port.postMessage(message, [chunk.buffer]);
-        if (message.done) ended = true;
+        (transfer ??= [undefined])[0] = chunk.buffer;
+        try { port.postMessage(message, transfer); }
+        finally { transfer[0] = message.chunk = undefined; }
+        if (complete) ended = true;
       }
     },
     end() {
@@ -62,7 +76,7 @@ export function parentStreamChannel(port, id, cancelled) {
   let controller;
   let settlePull;
   let closed = false;
-  const body = new ReadableStream({
+  const body = ownFlightStream(new ReadableStream({
     start(value) { controller = value; },
     pull() {
       return new Promise(resolve => {
@@ -76,7 +90,7 @@ export function parentStreamChannel(port, id, cancelled) {
       port.postMessage({ id, type: 'cancel' });
       cancelled(reason);
     },
-  }, { highWaterMark: 0 });
+  }, { highWaterMark: 0 }));
   return {
     body,
     chunk(buffer, offset = 0, length = buffer?.byteLength) {

package/runtime/app-stream-html.mjs

@@ -1,5 +1,5 @@
 import {reportRequestError,acknowledgeRequestError} from './instrumentation.mjs';
-import { htmlEnvelope } from './html-envelope.mjs';
+import { htmlEnvelope, flightBootstrap } from './html-envelope.mjs';
 import React from 'react';
 import { fontPreloads } from './font-preload.mjs';
 import { isDynamicBailout } from '../compat/dynamic-bailout.cjs';
@@ -16,11 +16,14 @@ import { streamSelector } from './stream-select.mjs';
 import {nodeHtmlReader,useNodeHtml} from './node-html-stream.mjs';
 
 import {flightTap} from './flight-tap.mjs';
+import {createFlightMeasurement} from './flight-diagnostics.mjs';
 
 export async function renderProgressiveAppHtml({ result, request, route, responseHeaders, decodeFlight, signal, timeoutMs, partial }) {
   timeoutMs ??= route?.cacheConfig?.maxDuration ? route.cacheConfig.maxDuration * 1000 : 25_000;
   const nonceAttribute = request.nonce ? ` nonce="${escapeHtml(request.nonce)}"` : '';
-  const tap = flightTap(result.body);
+  const measurement = createFlightMeasurement(request, 'ssr');
+  const tap = flightTap(result.body, measurement);
+  let status = result.status;
   const abort = new AbortController();
   const timeout = setTimeout(() => abort.abort(appTimeoutError('HTML stream', timeoutMs)), timeoutMs);
   const combinedSignal = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
@@ -29,7 +32,11 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
   let committed = Boolean(partial?.shellSent);
   let control;
   let model;
+  let bootstrapFlight;
+  const failed = error => measurement?.finish(error?.statusCode === 504 || combinedSignal.reason?.statusCode === 504
+    ? 'timedOut' : combinedSignal.aborted ? 'cancelled' : 'failed', status);
   const cancel = async reason => {
+    measurement?.finish(reason?.statusCode === 504 ? 'timedOut' : 'cancelled', status);
     clearTimeout(timeout);
     combinedSignal.removeEventListener('abort', onAbort);
     if (!abort.signal.aborted) abort.abort(reason || new Error('App Router response was cancelled'));
@@ -39,6 +46,7 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
   combinedSignal.addEventListener('abort', onAbort, { once: true });
   try {
     model = await decodeFlight(tap.body, request.clientModules, request.distDir, { production: request.production });
+    measurement?.mark('modelReady');
     const renderOptions = {
       signal: combinedSignal,
       nonce: request.nonce,
@@ -81,15 +89,17 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
     }
     const styles = fontPreloads(route.fonts, request.nonce) + (model.css ?? route.css ?? []).map(href => `<link rel="stylesheet" href="${escapeHtml(href)}">`).join('');
     if (styles && !partial) prefix = prefix.replace(/<\/head>/i, `${styles}</head>`);
+    measurement?.mark('shellReady');
     tap.startOutput();
     committed = true;
     const body = (async function* () {
       let total = 0;
       const envelope = htmlEnvelope({ resumed: Boolean(partial) });
       const encode = value => {
-        const bytes = Buffer.from(value);
+        const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
         total += bytes.byteLength;
         if (total > MAX_RESPONSE_BYTES) throw new Error('Response exceeds the 16 MiB PRNext limit');
+        if (measurement) measurement.responseBytes = total;
         return bytes;
       };
       let flightDone = false;
@@ -116,9 +126,8 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
           } else {
             if (next.done) { flightDone = true; }
             else {
-              const encoded = Buffer.from(next.value.buffer, next.value.byteOffset, next.value.byteLength).toString('base64');
               selection.watch('flight', tap.next());
-              yield encode(`<script${nonceAttribute}>(self.__PRNEXT_FLIGHT_STREAM__||=[]).push("${encoded}");document.currentScript.remove()</script>`);
+              yield encode((bootstrapFlight ??= flightBootstrap(nonceAttribute))(next.value));
             }
           }
           if (control) {
@@ -128,6 +137,10 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
           }
         }
         yield encode(`<script${nonceAttribute}>self.__PRNEXT_FLIGHT_STREAM__.push(null);document.currentScript.remove()</script>` + envelope.finish());
+        measurement?.finish('completed', status);
+      } catch (error) {
+        failed(error);
+        throw error;
       } finally {
         selection.close();
         combinedSignal.removeEventListener('abort', onAbort);
@@ -136,7 +149,7 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
     })();
     // An error encoded in Flight may be contained by a valid Suspense shell.
     // Ordinary GET errors select HTTP 500 only when that shell also fails.
-    const status = result.rscError && result.status === 500 && ['GET', 'HEAD'].includes(request.method) ? 200 : result.status;
+    status = result.rscError && result.status === 500 && ['GET', 'HEAD'].includes(request.method) ? 200 : result.status;
     return { status, headers: { ...responseHeaders, ...result.headers, 'content-type': 'text/html; charset=utf-8' }, body, cancel };
   } catch (error) {
     if (!committed && !combinedSignal.aborted && error?.statusCode !== 504 &&
@@ -151,13 +164,16 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
           (route.client ? `<script type="module" async${nonceAttribute} src="${escapeHtml(route.client)}"></script>` : '');
         const prefix = shell.slice(0, end) + bootstrap;
         const closing = shell.slice(end);
+        status = route.parallel && navigationResponse(error)?.status === 404 ? 404 : 500;
+        measurement?.mark('shellReady');
         tap.startOutput();
         const body = (async function* () {
           let total = 0;
           const encode = value => {
-            const bytes = Buffer.from(value);
+            const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
             total += bytes.byteLength;
             if (total > MAX_RESPONSE_BYTES) throw new Error('Response exceeds the 16 MiB PRNext limit');
+            if (measurement) measurement.responseBytes = total;
             return bytes;
           };
           try {
@@ -166,18 +182,21 @@ export async function renderProgressiveAppHtml({ result, request, route, respons
               combinedSignal.throwIfAborted();
               const next = await tap.next();
               if (next.done) break;
-              const encoded = Buffer.from(next.value.buffer, next.value.byteOffset, next.value.byteLength).toString('base64');
-              yield encode(`<script${nonceAttribute}>(self.__PRNEXT_FLIGHT_STREAM__||=[]).push("${encoded}");document.currentScript.remove()</script>`);
+              yield encode((bootstrapFlight ??= flightBootstrap(nonceAttribute))(next.value));
             }
             yield encode(`<script${nonceAttribute}>self.__PRNEXT_FLIGHT_STREAM__.push(null);document.currentScript.remove()</script>` + closing);
-          } finally { await cancel(); }
+            measurement?.finish('completed', status);
+          } catch (failure) { failed(failure); throw failure; }
+          finally { await cancel(); }
         })();
-        return { status: route.parallel && navigationResponse(error)?.status === 404 ? 404 : 500, headers: { ...responseHeaders, ...result.headers, 'content-type': 'text/html; charset=utf-8' }, body, cancel };
+        return { status, headers: { ...responseHeaders, ...result.headers, 'content-type': 'text/html; charset=utf-8' }, body, cancel };
       } catch (recoveryError) {
+        failed(recoveryError);
         await cancel(recoveryError);
         throw combinedSignal.reason?.statusCode === 504 ? combinedSignal.reason : recoveryError;
       }
     }
+    failed(error);
     combinedSignal.removeEventListener('abort', onAbort);
     await cancel(error);
     if (combinedSignal.reason?.statusCode === 504) throw combinedSignal.reason;

package/runtime/app-styles.mjs

@@ -32,7 +32,23 @@ export function appStyleManager(document, { timeout = 15_000 } = {}) {
       if (!records.length) sheets.delete(href);
     }
   }
-  function acquire(href, before, replace = false) {
+  // Initial HTML can contain many sheets. Index it once per synchronous
+  // prepare/commit operation, lazily when an untracked URL needs adoption.
+  // Never retain this snapshot across operations: external links may change.
+  function initialSheets() {
+    let index;
+    return (href, tracked) => {
+      if (!index) {
+        index = new Map();
+        for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+          const url = link.href, links = index.get(url) || [];
+          links.push(link); index.set(url, links);
+        }
+      }
+      return index.get(href)?.find(link => !tracked.has(link));
+    };
+  }
+  function acquire(href, before, replace = false, initial = initialSheets()) {
     const records = sheets.get(href) || [];
     const current = records.at(-1);
     if (current && !replace) return current;
@@ -40,7 +56,7 @@ export function appStyleManager(document, { timeout = 15_000 } = {}) {
     // in place until commit. Discard older abandoned candidates immediately.
     if (replace) for (const record of [...records]) if (!record.active && !record.recovery && !reserved(record)) remove(href, record);
     const tracked = new Set(records.map(record => record.link));
-    const existing = replace ? undefined : [...document.querySelectorAll('link[rel="stylesheet"]')].find(link => link.href === href && !tracked.has(link));
+    const existing = replace ? undefined : initial(href, tracked);
     const link = existing || document.createElement('link');
     const sheet = { link, active: !!existing, ready: !!existing?.sheet, recovery: false };
     const retained = sheets.get(href) || [];
@@ -77,6 +93,7 @@ export function appStyleManager(document, { timeout = 15_000 } = {}) {
     async prepare(values = [], signal) {
       if (signal?.aborted) throw aborted();
       const wanted = urls(values);
+      const initial = initialSheets();
       const prepared = [];
       let before;
       // Establish cascade order before downloading. Re-inserting an already
@@ -85,7 +102,7 @@ export function appStyleManager(document, { timeout = 15_000 } = {}) {
       // when an existing sheet would otherwise need to move across that suffix.
       for (let index = wanted.length - 1; index >= 0; index--) {
         const href = wanted[index];
-        let sheet = acquire(href, before);
+        let sheet = acquire(href, before, false, initial);
         if (before && !(sheet.link.compareDocumentPosition(before) & 4)) sheet = acquire(href, before, true);
         prepared.push(sheet.promise);
         before = sheet.link;
@@ -113,12 +130,13 @@ export function appStyleManager(document, { timeout = 15_000 } = {}) {
     commit(values = []) {
       cleanup++;
       const wanted = new Set(urls(values));
+      const initial = initialSheets();
       const handedUrls = [...handed.keys()];
       const pinned = wanted.size === handed.size && [...wanted].every((href, index) => handedUrls[index] === href) ? handed : null;
       for (const href of wanted) {
         const records = sheets.get(href) || [];
         const prior = !pinned && handed.size ? records.find(record => record.active) || records.find(record => record.recovery) : undefined;
-        const sheet = pinned?.get(href) || prior || records.findLast(record => record.ready) || acquire(href);
+        const sheet = pinned?.get(href) || prior || records.findLast(record => record.ready) || acquire(href, undefined, false, initial);
         // Initial HTML links are render-blocking. A missing sheet is restored
         // on explicit recovery; normal navigation always prepares first.
         sheet.active = true; sheet.recovery = false; sheet.link.media = '';

package/runtime/cache-components-rsc.mjs

@@ -4,6 +4,7 @@ import { actionManifest, registerCacheClientModule } from './action-server.mjs';
 import { codecSymbol } from '../compat/use-cache.cjs';
 import { encodeCacheArguments } from './cache-arguments.mjs';
 import { flightBundler } from './worker-metadata.mjs';
+import {primitiveCacheResult,flightCacheResult,isCacheResultPacket,readCacheResult,CACHE_RESULT_KEY_VERSION,CACHE_RESULT_LIMIT} from './cache-result.mjs';
 const consumers = new WeakMap();
 const emptyModules = Object.freeze({});
 
@@ -32,6 +33,7 @@ export function flightConsumer(context) {
 }
 
 globalThis[codecSymbol] = {
+  cacheKeyVersion:CACHE_RESULT_KEY_VERSION,
   async arguments(values, context) {
     const temporaryReferences = clientReferences();
     const body = await encodeReply(values, { temporaryReferences, signal: context.signal });
@@ -41,27 +43,45 @@ globalThis[codecSymbol] = {
     return { key, values: decoded, temporaryReferences, serverTemporaryReferences };
   },
   async render(callback, encoded, context) {
+    context.signal?.throwIfAborted();
     const bundler = flightBundler(context.clientModules, false);
     let failure;
     // React calls then inside its rendering context, preserving React.cache isolation.
     // React can subscribe more than once while unwrapping a thenable. Start
     // lazily in its rendering context, but never execute the producer twice.
-    let execution;
-    const result = { then(resolve, reject) { (execution ||= Promise.resolve().then(callback)).then(resolve, reject); } };
+    let execution,checked=false,primitive;
+    const result = { then(resolve, reject) { (execution ||= Promise.resolve().then(callback)).then(value=>{
+      try{
+        context.signal?.throwIfAborted();
+        if(!checked){primitive=primitiveCacheResult(value);checked=true;}
+        // The producer still runs inside the official renderer exactly once.
+        // Do not return the original object through another Promise: that would
+        // inspect a user-defined then getter again before React receives it.
+        resolve(primitive?null:value);
+      }catch(error){reject(error);}
+    },reject); } };
     const stream = renderToReadableStream(result, bundler, { signal: context.signal, temporaryReferences: encoded.serverTemporaryReferences, onError(error) { failure ||= error; return 'PRNextCacheRenderError'; } });
     const chunks = [];
     let size = 0;
     for await (const value of stream) {
       size += value.byteLength;
       if (size > 16 * 1024 * 1024) throw new Error('Cached React result exceeds the 16 MiB rendering limit');
-      chunks.push(Buffer.from(value));
+      // React exposes an official type:'bytes' Web stream: each delivered
+      // Uint8Array owns its storage. Keep it until the sole packet aggregate;
+      // copy Buffers/other representations defensively instead.
+      chunks.push(value instanceof Uint8Array&&!Buffer.isBuffer(value)?value:Buffer.from(value));
     }
     if (failure) throw failure;
-    // Each chunk above is already an owned copy. A single chunk needs no
-    // second allocation; never expose the producer's mutable stream storage.
-    return chunks.length===1?chunks[0]:Buffer.concat(chunks, size);
+    context.signal?.throwIfAborted();
+    // The packet always owns a final aggregate; no producer storage escapes.
+    return primitive||flightCacheResult(chunks,size);
   },
   async decode(bytes, encoded, context) {
+    if(isCacheResultPacket(bytes)){
+      const result=readCacheResult(bytes);
+      if(!result.flight)return result.value;
+      bytes=result.flight;
+    }else if(bytes.length>CACHE_RESULT_LIMIT)throw new Error('Invalid RSC cache result envelope');
     return createFromReadableStream(new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); } }), {
       serverConsumerManifest: flightConsumer(context), temporaryReferences: encoded.temporaryReferences, replayConsoleLogs: false,
     });

package/runtime/cache-result.mjs

@@ -0,0 +1,58 @@
+// Private, versioned cache bytes. These packets never become browser Flight.
+import {isUtf8} from 'node:buffer';
+const MAGIC=Buffer.from([0x50,0x52,0x4e,0x43,2]);
+const HEADER=MAGIC.length+1;
+export const CACHE_RESULT_LIMIT=16*1024*1024;
+export const CACHE_RESULT_KEY_VERSION='flight-primitives-v2';
+const SCALAR_LIMIT=CACHE_RESULT_LIMIT-64*1024;
+function packet(type,payload=Buffer.alloc(0)){
+  if(payload.length>CACHE_RESULT_LIMIT)throw new Error('Cached React result exceeds the 16 MiB rendering limit');
+  const bytes=Buffer.allocUnsafe(HEADER+payload.length);MAGIC.copy(bytes);bytes[MAGIC.length]=type;payload.copy(bytes,HEADER);return bytes;
+}
+function textPacket(type,value,length){
+  const bytes=Buffer.allocUnsafe(HEADER+length);MAGIC.copy(bytes);bytes[MAGIC.length]=type;bytes.write(value,HEADER,length,'utf8');return bytes;
+}
+export function primitiveCacheResult(value){
+  if(value===null)return packet(1);
+  switch(typeof value){
+    case 'undefined':return packet(2);
+    case 'boolean':return packet(value?3:4);
+    case 'number':{const bytes=Buffer.allocUnsafe(8);bytes.writeDoubleLE(value);return packet(5,bytes);}
+    case 'bigint':{const text=String(value);return text.length>SCALAR_LIMIT?undefined:textPacket(6,text,text.length);}
+    case 'string':{
+      // Leave framing-sensitive boundary values to the official Flight limit.
+      if(value.length>SCALAR_LIMIT)return undefined;
+      // Flight's small JSON strings and large UTF8 text rows do not normalize
+      // lone surrogates or BOMs alike. Keep any such string on the fallback,
+      // independently of React's text-row threshold or chunk boundaries.
+      if(!value.isWellFormed()||value.includes('\ufeff'))return undefined;
+      const length=Buffer.byteLength(value);
+      if(length>SCALAR_LIMIT)return undefined;
+      return textPacket(7,value,length);
+    }
+    // In particular, do not enumerate objects, inspect then, or read a proxy or
+    // getter. React owns every nonprimitive result and its temporary references.
+    default:return undefined;
+  }
+}
+export function flightCacheResult(chunks,size){
+  if(size>CACHE_RESULT_LIMIT)throw new Error('Cached React result exceeds the 16 MiB rendering limit');
+  // Ordinary Flight keeps its original bytes and sole aggregate copy. Reserve
+  // the whole first-byte family for this private protocol, without assuming
+  // anything about React's current or future row syntax. Inspect the aggregate
+  // so an empty leading chunk cannot hide a reserved first byte.
+  const bytes=Buffer.concat(chunks,size);
+  return isCacheResultPacket(bytes)?packet(0,bytes):bytes;
+}
+export function isCacheResultPacket(bytes){return bytes[0]===MAGIC[0];}
+export function readCacheResult(bytes){
+  if(!Buffer.isBuffer(bytes)||bytes.length<HEADER||bytes.length>HEADER+CACHE_RESULT_LIMIT||!bytes.subarray(0,MAGIC.length).equals(MAGIC))throw new Error('Invalid RSC cache result envelope');
+  const type=bytes[MAGIC.length],payload=bytes.subarray(HEADER);
+  // Unwrap an escaped raw payload once; never interpret it as another packet.
+  if(type===0&&isCacheResultPacket(payload))return {flight:payload};
+  if(type>=1&&type<=4&&payload.length===0)return {value:type===1?null:type===2?undefined:type===3};
+  if(type===5&&payload.length===8)return {value:payload.readDoubleLE()};
+  if(type===6&&payload.length&&/^(?:0|-?[1-9]\d*)$/.test(payload.toString()))return {value:BigInt(payload.toString())};
+  if(type===7&&isUtf8(payload))return {value:payload.toString()};
+  throw new Error('Invalid RSC cache result envelope');
+}

package/runtime/compile-cache-retention.mjs

@@ -0,0 +1,53 @@
+import {lstat,opendir,unlink,realpath} from 'node:fs/promises';
+import path from 'node:path';
+import {captureStorageDirectory,verifyStorageDirectories,sameStoragePath} from './storage-path.mjs';
+import {withBuildLock} from './project-lock.mjs';
+
+/** Bounded maintenance of a known, disposable compiler namespace. Open V8
+ * cache readers remain valid; an evicted future lookup is a cache miss. */
+export async function pruneCompilerCache(directory,{maxBytes=64*1024*1024,maxFiles=2048}={}){
+  if(!directory)return;
+  try{
+    const snapshot=await captureStorageDirectory(directory);if(!snapshot)return;
+    return await withBuildLock(directory,async canonical=>{
+      if(!sameStoragePath(canonical,directory)||!await verifyStorageDirectories([snapshot]))return;
+      return prune(canonical,{maxBytes,maxFiles});
+    });
+  }
+  catch{/* A busy or unverifiable maintenance owner wins; never wait on it. */}
+}
+async function prune(directory,{maxBytes,maxFiles}){
+  try{
+    const files=[];let scanned=0,complete=true;
+    const input=await lstat(directory);if(!input.isDirectory()||input.isSymbolicLink())return;
+    directory=await realpath(directory);
+    const initial=await captureStorageDirectory(directory);if(!initial)return;
+    async function collect(folder,depth,parents){
+      if(depth>3){complete=false;return;}
+      const snapshot=await captureStorageDirectory(folder),guards=[...parents,snapshot];
+      if(!snapshot||!await verifyStorageDirectories(guards)){complete=false;return;}
+      const entries=await opendir(folder);
+      for await(const entry of entries){
+        if(++scanned>8192){complete=false;break;}
+        if(entry.name.startsWith('.'))continue;
+        const name=path.join(folder,entry.name),info=await lstat(name).catch(()=>null);
+        if(!info||info.isSymbolicLink())continue;
+        if(info.isDirectory())await collect(name,depth+1,guards);
+        else if(info.isFile())files.push({name,size:info.size,time:info.mtimeMs,ino:info.ino,dev:info.dev,guards});
+        if(!complete)break;
+      }
+      if(!await verifyStorageDirectories(guards))complete=false;
+    }
+    const info=await lstat(directory);if(!info.isDirectory()||info.isSymbolicLink())return;
+    await collect(directory,0,[initial]);if(!complete)return;
+    files.sort((a,b)=>b.time-a.time);let bytes=0,retained=0;
+    for(let i=0;i<files.length;i++){
+      const file=files[i];
+      if(retained>=maxFiles||bytes+file.size>maxBytes){
+        if(!await verifyStorageDirectories(file.guards))return;
+        const current=await lstat(file.name).catch(()=>null);
+        if(current?.isFile()&&!current.isSymbolicLink()&&current.ino===file.ino&&current.dev===file.dev&&current.mtimeMs===file.time&&current.size===file.size&&sameStoragePath(await realpath(file.name),file.name)&&await verifyStorageDirectories(file.guards))await unlink(file.name).catch(()=>{});
+      }else{bytes+=file.size;retained++;}
+    }
+  }catch{/* Compiler cache retention cannot fail a request or build. */}
+}

package/runtime/compile-cache.mjs

@@ -1,8 +1,35 @@
 import {flushCompileCache} from 'node:module';
+import {lstatSync,realpathSync,writeFileSync,unlinkSync} from 'node:fs';
+import {randomUUID} from 'node:crypto';
+import {hostname} from 'node:os';
+import path from 'node:path';
+import {pruneCompilerCache} from './compile-cache-retention.mjs';
 let pending;
+let managedDirectory;
+let lastMaintenance=0,maintenance;
+// Native workers opt in explicitly. Never maintain a caller-supplied global
+// NODE_COMPILE_CACHE, and reject links in both framework-owned path components.
+try{
+  const root=process.env.PRNEXT_MANAGED_COMPILE_CACHE_ROOT;
+  if(root&&process.env.NODE_COMPILE_CACHE&&process.env.NODE_DISABLE_COMPILE_CACHE!=='1'){
+    const canonical=realpathSync(root),base=path.join(canonical,'.prnext-cache'),directory=path.join(base,'node-compile-v1');
+    if(realpathSync(process.env.NODE_COMPILE_CACHE)===directory&&[base,directory,process.env.NODE_COMPILE_CACHE].every(folder=>{const info=lstatSync(folder);return info.isDirectory()&&!info.isSymbolicLink();})){
+      const lease=path.join(directory,`.lease-${process.pid}-${randomUUID()}.json`);
+      writeFileSync(lease,JSON.stringify({pid:process.pid,host:hostname()}),{flag:'wx',mode:0o600});
+      managedDirectory=directory;
+      process.once('exit',()=>{try{unlinkSync(lease);}catch{}});
+    }
+  }
+}catch{/* A lease failure leaves this process's cache unmanaged. */}
 // Flush after imports settle so later workers can reuse compiled code even
 // while this worker stays warm. Disk failure is an optimization miss only.
 export function scheduleCompileCacheFlush(){
   if(pending||!process.env.NODE_COMPILE_CACHE||process.env.NODE_DISABLE_COMPILE_CACHE==='1')return;
-  pending=setTimeout(()=>{pending=undefined;try{flushCompileCache();}catch{}},1000);pending.unref();
+  pending=setTimeout(()=>{
+    pending=undefined;try{flushCompileCache();}catch{}
+    if(managedDirectory&&!maintenance&&Date.now()-lastMaintenance>=60000){
+      lastMaintenance=Date.now();
+      maintenance=pruneCompilerCache(managedDirectory,{maxBytes:128*1024*1024,maxFiles:4096}).finally(()=>{maintenance=undefined;});
+    }
+  },1000);pending.unref();
 }