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

package/runtime/app-client.mjs

@@ -1,6 +1,6 @@
 import { deploymentHeaders, assertDeploymentResponse } from './deployment-client.mjs';
 import React, { startTransition, useLayoutEffect } from 'react';
-import { preload } from 'react-dom';
+import { preload, flushSync } from 'react-dom';
 import { PARTIAL_PREFETCH_TYPE, PARTIAL_PREFETCH_CACHE_BYTES } from './app-prefetch-constants.mjs';
 import { isDynamicBailout } from '../compat/dynamic-bailout.cjs';
 import { createRoot, hydrateRoot } from 'react-dom/client';
@@ -21,6 +21,7 @@ import {recoverNavigation} from './navigation-recovery.mjs';
 import { createActivityCache } from '../compat/activity-cache.cjs';
 import { createFlightTransport, TYPE as FLIGHT_DELTA_TYPE } from '../compat/flight-delta.cjs';
 import {decodeBase64} from '../compat/base64.cjs';
+import { supersedableDevelopmentFlight, developmentFlightRoot } from './development-flight.mjs';
 
 const PREFETCH_LIMIT = 8;
 const PREFETCH_LIFETIME = 30_000;
@@ -258,6 +259,10 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   let historyRouting = currentRouting;
   let currentModel = initialModel;
   let committedView = { model: initialModel, routing: currentRouting, url: currentUrl.href, retentionEpoch: 0, authorizationEpoch: 0 };
+  // Development navigation can display a newer component generation before its
+  // last Flight row arrives. Keep that visible tree separately from the last
+  // genuinely complete response; superseding it must not restore older types.
+  let developmentView;
   let pendingView, pendingNavigation;
   const historyFocus = new Map();
   let currentKey = window.history.state?.__prnext?.key || 0;
@@ -290,46 +295,57 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       // A committed loading shell can still contain rows owned by a live
       // fetch. Keep the last fully received view available before aborting it.
       // Authorized PPR previews likewise never become the canonical model.
-      if (canonical) committedView = { model, routing: model.routing, url, retentionEpoch: controller._retentionEpoch, authorizationEpoch: controller._authorizationEpoch };
+      if (canonical) {
+        committedView = { model, routing: model.routing, url, element, retentionEpoch: controller._retentionEpoch, authorizationEpoch: controller._authorizationEpoch };
+        developmentView = undefined;
+      }
     };
     if (flight) flight.committed = promote;
-    startTransition(() => root.render(appView({ model, controller, url, globalErrorComponent, globalErrorCss,
+    const element = appView({ model, controller, url, globalErrorComponent, globalErrorCss,
       committed: () => {
         if (token !== navigation || pendingView !== view) return;
         view.committed = true;
+        if (canonical && flight?.development && kind !== 'action') developmentView = { model, routing: model.routing, url, element, retentionEpoch: controller._retentionEpoch, authorizationEpoch: controller._authorizationEpoch };
         promote();
         committed?.();
       },
-    })));
+    });
+    view.element = element;
+    startTransition(() => root.render(element));
   }
 
   function abandonPendingView() {
     if (!pendingView) return true;
     const flight = navigationStreams.get(pendingView.model);
     const strictAuthorization = controller._navigationCache?.authCookies !== undefined;
+    const retained = developmentView || committedView;
     if (flight) flight.committed = undefined;
     if (pendingView.kind === 'action' && committedView.authorizationEpoch === controller._authorizationEpoch &&
         (!strictAuthorization || committedView.model.authorizationKey === currentModel.authorizationKey)) {
       // An action's received result can invoke a returned action before React
       // commits its UI. This response is never owned/aborted by activeRequest;
       // adopt its model instead of rolling back the prior mutation's epoch.
+      committedView = { model: currentModel, routing: currentRouting, url: currentUrl.href, element: pendingView.element, retentionEpoch: controller._retentionEpoch, authorizationEpoch: controller._authorizationEpoch };
       pendingView = undefined;
-      committedView = { model: currentModel, routing: currentRouting, url: currentUrl.href, retentionEpoch: controller._retentionEpoch, authorizationEpoch: controller._authorizationEpoch };
+      developmentView = undefined;
       return true;
     }
     // A new authorized shell or explicit invalidation can make the last full
     // model private to an obsolete session. Reauthorize through a document
     // request instead of briefly restoring that model while C is pending.
-    if ((strictAuthorization && committedView.model.authorizationKey !== currentModel.authorizationKey) ||
-        committedView.retentionEpoch !== controller._retentionEpoch ||
-        committedView.authorizationEpoch !== controller._authorizationEpoch) return false;
+    if ((strictAuthorization && retained.model.authorizationKey !== currentModel.authorizationKey) ||
+        retained.retentionEpoch !== controller._retentionEpoch ||
+        retained.authorizationEpoch !== controller._authorizationEpoch ||
+        (retained.model.rootLayout && currentModel.rootLayout && retained.model.rootLayout !== currentModel.rootLayout)) return false;
     pendingView = undefined;
-    currentModel = committedView.model;
-    currentRouting = committedView.routing;
+    currentModel = retained.model;
+    currentRouting = retained.routing;
     // React can already be reading a lazy row after createFromFetch resolves
     // the root model. Replace that suspended render before abort rejects its
     // remaining rows; it must not poison the retained layout or page cache.
-    root.render(appView({ model: committedView.model, controller, url: committedView.url, globalErrorComponent, globalErrorCss }));
+    // Reuse the exact submitted element. Before a replacement refresh commits,
+    // rebuilding the older Flight lazies after Refresh can itself remount them.
+    root.render(retained.element || appView({ model: retained.model, controller, url: retained.url, globalErrorComponent, globalErrorCss }));
     return true;
   }
 
@@ -371,7 +387,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   const actionReloadError = () => new Error('The session changed while this page was loading. Reload before repeating the action.');
 
   const flightTransport = createFlightTransport();
-  async function requestFlight(url, signal, routing = currentRouting, onPartial, {skipEnsure=false,fullFlight=false}={}) {
+  async function requestFlight(url, signal, routing = currentRouting, onPartial, {skipEnsure=false,fullFlight=false,developmentSupersession}={}) {
     if(process.env.NODE_ENV==='development'&&!routing?.refresh&&!skipEnsure)await globalThis.__PRNEXT_DEV__?.ensureRoute?.(url.href);
     const exported = window.__PRNEXT_STATIC_EXPORT__ === true;
     const base = !exported && !fullFlight ? flightTransport.snapshot() : undefined;
@@ -392,12 +408,17 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     }
     await onPartial?.(response, destination);
     let model;
-    const flight = { complete: false };
-    try { model = assertModel(await createFromFetch(Promise.resolve(await flightTransport.response(response,base,{onEnd(){flight.complete = true;flight.committed?.();}})), flightOptions)); }
+    const flight = { complete: false, development: process.env.NODE_ENV === 'development' && !!developmentSupersession };
+    try {
+      const received = await flightTransport.response(response,base,{onEnd(){flight.complete = true;flight.committed?.();}});
+      if (process.env.NODE_ENV === 'development' && developmentSupersession) {
+        model = assertModel(await developmentFlightRoot(createFromReadableStream(supersedableDevelopmentFlight(received.body, developmentSupersession), { ...flightOptions, unstable_allowPartialStream: true }), signal));
+      } else model = assertModel(await createFromFetch(Promise.resolve(received), flightOptions));
+    }
     catch(error) {
       if(!delta||fullFlight||signal?.aborted)throw error;
       flightTransport.clear();
-      return requestFlight(url,signal,routing,onPartial,{skipEnsure:true,fullFlight:true});
+      return requestFlight(url,signal,routing,onPartial,{skipEnsure:true,fullFlight:true,developmentSupersession});
     }
     navigationStreams.set(model, flight);
     model.router.basePath = basePath;
@@ -406,7 +427,11 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     return { model, url: destination };
   }
 
-  const navigateFlight=(url,signal,...args)=>recoverNavigation(recoverySignal=>requestFlight(url,recoverySignal,...args),{signal});
+  // Only development navigation GETs may retain a DOM-committed partial tree.
+  // Direct prefetch, production navigation and Action POST decoders stay strict.
+  const navigateFlight=(url,signal,routing,onPartial,options={})=>recoverNavigation(recoverySignal=>requestFlight(url,recoverySignal,routing,onPartial,{
+    ...options, ...(process.env.NODE_ENV === 'development' ? { developmentSupersession: signal } : {}),
+  }),{signal});
 
   const requestPartial = (typeof __PRNEXT_CACHE_COMPONENTS__ === 'undefined' ? cacheComponents : __PRNEXT_CACHE_COMPONENTS__) ? async function requestPartial(url, signal, full = false) {
     const response = await fetch(url.href, { credentials: 'same-origin', signal,
@@ -507,10 +532,10 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
 
   async function waitForDevelopmentUpdate() {
     // A generation updates the Flight loader before React Refresh registers
-    // the replacement component families. An already-running action may finish
-    // in that interval; rendering its model immediately remounts those client
-    // components and loses layout state. Wait only on development bookkeeping,
-    // never replay the mutation or cancel a newer user navigation.
+    // the replacement component families. An already-running Flight request
+    // may finish in that interval; rendering its model immediately can remount
+    // those client components and lose layout state. Wait only on development
+    // bookkeeping, never replay a request or cancel a newer user navigation.
     let development = globalThis.__PRNEXT_DEV__;
     while (development?.applying && development.applied) {
       await development.applied;
@@ -596,14 +621,19 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     return outcome();
   }
 
-  async function navigate(href, { replace = false, scroll = true, pop = false, savedScroll, savedRouting, refresh = false } = {}) {
-    if (pageHidden || documentFallback) return;
+  async function navigate(href, { replace = false, scroll = true, pop = false, savedScroll, savedRouting, refresh = false, developmentSignal } = {}) {
+    if (developmentSignal?.aborted) return false;
+    if (pageHidden || documentFallback) return developmentSignal ? false : undefined;
     const target = navigationUrl(href);
     if (!isApplicationURL(target, window.location.origin, basePath) || isHtmlDocumentRoute(htmlOnlyRoutes, removeBasePath(target.pathname, basePath))) {
       fallbackDocument(target.href, replace);
-      return;
+      return developmentSignal ? false : undefined;
     }
     const token = ++navigation;
+    // The compiler generation may remain valid when an ordinary navigation or
+    // Action replaces only its pending UI. This is distinct from a DOM commit,
+    // an owner cancellation, or a genuine failed request.
+    const superseded = () => developmentSignal && token !== navigation && !developmentSignal.aborted && !pageHidden && !documentFallback ? 'superseded' : false;
     const intent = { token, url: target.href, replace: replace || pop || refresh };
     pendingNavigation = intent;
     finishCommit?.();
@@ -615,7 +645,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     activeRequest = undefined;
     if (!restored) {
       fallbackDocument(target.href, replace || pop || refresh);
-      return;
+      return developmentSignal ? false : undefined;
     }
 
     function updateHistory(destination) {
@@ -639,7 +669,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       updateHistory(target);
       if (scroll) scrollToTarget(target, savedScroll);
       if (pendingNavigation === intent) pendingNavigation = undefined;
-      return;
+      return developmentSignal ? false : undefined;
     }
 
     const cacheKey = `${target.origin}${target.pathname}${target.search}`;
@@ -669,6 +699,8 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
           const abort = new AbortController();
           activeRequest = abort;
           result = await navigateFlight(target, abort.signal, currentRouting, async (response, destination) => {
+            if (process.env.NODE_ENV === 'development') await waitForDevelopmentUpdate();
+            if (token !== navigation || abort.signal.aborted) return;
             // A cached shell (including any cached authorization key) cannot
             // establish this request's live session identity. Strict account
             // isolation waits for the freshly authorized Flight model instead.
@@ -680,6 +712,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
             if (destination.pathname !== preview.url.pathname || destination.search !== preview.url.search) return;
             prepareLayoutCache(preview.model, currentModel);
             await appStyleManager(document).prepare(preview.model.css || [], abort.signal);
+            if (process.env.NODE_ENV === 'development') await waitForDevelopmentUpdate();
             if (token !== navigation || abort.signal.aborted) return;
             updateHistory(destination); historyUpdated = true;
             appStyleManager(document).handoff(preview.model.css || []);
@@ -692,19 +725,26 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
         // A refresh is already inside the compiler's apply transaction. Calling
         // ensureRoute from here can wait for that same transaction forever when
         // this tree has no routing state (the ordinary single-route case).
-        result = await navigateFlight(target, abort.signal, pop && savedRouting ? { ...savedRouting, restore: true } : refresh && currentRouting ? { ...currentRouting, refresh: true } : currentRouting, undefined, {skipEnsure:refresh});
+        const signal = developmentSignal ? AbortSignal.any([abort.signal, developmentSignal]) : abort.signal;
+        result = await navigateFlight(target, signal, pop && savedRouting ? { ...savedRouting, restore: true } : refresh && currentRouting ? { ...currentRouting, refresh: true } : currentRouting, undefined, {skipEnsure:refresh,developmentSupersession:developmentSignal ? signal : undefined});
       }
-      if (token !== navigation) return;
+      // Internal refreshes execute inside applyUpdate and must never wait on
+      // their own transaction. Ordinary navigations can already be in flight
+      // when an on-demand route publishes another client-module generation.
+      if (process.env.NODE_ENV === 'development' && !refresh) await waitForDevelopmentUpdate();
+      if (token !== navigation || activeRequest?.signal.aborted || developmentSignal?.aborted) return superseded();
       if (!isApplicationURL(result.url, window.location.origin, basePath)) throw new Error('The navigation destination requires a document request');
       if (result.model.rootLayout && currentModel.rootLayout && result.model.rootLayout !== currentModel.rootLayout) throw new Error('A different root layout requires a document request');
       if (requiresAuthorizedDocument(result.model)) {
         activeRequest?.abort();
         fallbackDocument(result.url.href, replace || pop || refresh);
-        return;
+        return developmentSignal ? false : undefined;
       }
       prepareLayoutCache(result.model, currentModel);
-      await appStyleManager(document).prepare(result.model.globalError ? [] : result.model.css || [], activeRequest?.signal);
-      if (token !== navigation) return;
+      const styleSignal = developmentSignal && activeRequest ? AbortSignal.any([activeRequest.signal, developmentSignal]) : activeRequest?.signal;
+      await appStyleManager(document).prepare(result.model.globalError ? [] : result.model.css || [], styleSignal);
+      if (process.env.NODE_ENV === 'development' && !refresh) await waitForDevelopmentUpdate();
+      if (token !== navigation || activeRequest?.signal.aborted || developmentSignal?.aborted) return superseded();
       currentRouting = result.model.routing;
       currentModel = result.model;
       historyRouting = currentRouting;
@@ -718,21 +758,32 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
         }
       };
       appStyleManager(document).handoff(result.model.globalError ? [] : result.model.css || []);
+      let didCommit = false;
       if(process.env.NODE_ENV==='development'&&refresh)await new Promise(resolve=>{
-        const finish=()=>{if(finishCommit===finish)finishCommit=undefined;resolve();};
+        const finish=()=>{developmentSignal?.removeEventListener('abort', finish);if(finishCommit===finish)finishCommit=undefined;resolve();};
         finishCommit=finish;
-        renderView(result.model, result.url.href, { token, committed: () => { committed(); finish(); } });
+        developmentSignal?.addEventListener('abort', finish, { once: true });
+        if (developmentSignal?.aborted) { finish(); return; }
+        renderView(result.model, result.url.href, { token, kind: developmentSignal ? 'development-refresh' : 'navigation', committed: () => { didCommit = true; committed(); finish(); } });
       });
       else renderView(result.model, result.url.href, { token, committed });
+      if (!developmentSignal) return;
+      if (developmentSignal.aborted || pageHidden || documentFallback) return false;
+      return didCommit || superseded();
     } catch (error) {
-      if (token !== navigation || error?.name === 'AbortError') return;
+      if (developmentSignal?.aborted) return false;
       if(error?.code==='PRNEXT_NAVIGATION_NETWORK'){
+        // A deadline failure is never evidence that only the UI was replaced.
+        if (token !== navigation) return false;
         window.dispatchEvent(new CustomEvent('prnext:navigation-error',{detail:{message:error.message}}));
-        return;
+        return developmentSignal ? false : undefined;
       }
+      if (token !== navigation) return error?.name === 'AbortError' ? superseded() : false;
+      if (error?.name === 'AbortError') return false;
       // Pages Router routes, public files, and unavailable Flight endpoints use
       // a normal document navigation, including the browser's redirect handling.
       fallbackDocument(target.href, replace || pop || refresh);
+      return developmentSignal ? false : undefined;
     } finally {
       if (pendingNavigation === intent) pendingNavigation = undefined;
       if (finishNavigation === releaseNavigation) finishNavigation = undefined;
@@ -740,7 +791,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     }
   }
 
-  function purgeRetainedPages() {
+  function purgeRetainedPages({ synchronous = false } = {}) {
     if (pageHidden || documentFallback) return false;
     saveScroll();
     if (!abandonPendingView()) {
@@ -751,9 +802,14 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     controller._retentionEpoch++;
     historyFocus.clear();
     if (committedView.model === currentModel && committedView.authorizationEpoch === controller._authorizationEpoch) committedView = { ...committedView, retentionEpoch: controller._retentionEpoch };
+    if (developmentView?.model === currentModel && developmentView.authorizationEpoch === controller._authorizationEpoch) developmentView = { ...developmentView, retentionEpoch: controller._retentionEpoch };
     // This only updates retention for the already committed model. It must
     // not become a new pending Flight view or a development commit barrier.
-    startTransition(() => root.render(appView({ model: currentModel, controller, url: committedView.url, globalErrorComponent, globalErrorCss })));
+    const element = appView({ model: currentModel, controller, url: (developmentView || committedView).url, globalErrorComponent, globalErrorCss });
+    if (committedView.model === currentModel) committedView = { ...committedView, element };
+    if (developmentView?.model === currentModel) developmentView = { ...developmentView, element };
+    if (synchronous) flushSync(() => root.render(element));
+    else startTransition(() => root.render(element));
     return true;
   }
 
@@ -813,6 +869,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   let resolveDevReady;
   const devReady=process.env.NODE_ENV==='development'?new Promise(resolve=>{resolveDevReady=resolve;}):undefined;
   const initialView = appView({ model: initialModel, controller, globalErrorComponent, globalErrorCss, ...(devReady?{committed:resolveDevReady}:{}) });
+  committedView.element = initialView;
   const rootOptions = {
     formState: initialModel.formState ?? null,
     onCaughtError(error) {
@@ -871,7 +928,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   return { root, router: controller, ...(process.env.NODE_ENV === 'development' ? {
     devReady,
     devStyles: routes => developmentStyles(currentModel, routes).css || [],
-    devPrepareStyles: routes => appStyleManager(document).prepare(developmentStyles(currentModel, routes).css || []),
+    devPrepareStyles: (routes, signal) => appStyleManager(document).prepare(developmentStyles(currentModel, routes).css || [], signal),
     devStylesApplied: (routes, { commit = true } = {}) => {
       for (const model of new Set([currentModel, committedView.model, pendingView?.model].filter(Boolean))) {
         const next = developmentStyles(model, routes);
@@ -880,7 +937,18 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       if (commit) appStyleManager(document).commit(currentModel.globalError ? [] : currentModel.css || []);
     },
     devPrepare: options => moduleLoader.updateModules(options.clientModules),
-    devCommit: () => {invalidatePrefetches();purgeRetainedPages();return navigate(new URL(window.location.href),{refresh:true});},
+    devBeforeRefresh: ({ navigation: routeOpening } = {}) => {
+      if (!routeOpening) { invalidatePrefetches(); return purgeRetainedPages({ synchronous: true }); }
+      // A cold route's module publication must not invalidate retained pages.
+      // Quiesce the old visible tree under its old families before Refresh,
+      // without changing epochs, cancelling the click, or committing its URL.
+      saveScroll();
+      if (!abandonPendingView()) { activeRequest?.abort(); fallbackDocument(currentUrl.href); return false; }
+      const retained = developmentView || committedView;
+      flushSync(() => root.render(retained.element));
+      return true;
+    },
+    devCommit: (_options, { signal } = {}) => navigate(new URL(window.location.href), { refresh: true, developmentSignal: signal }),
   } : {}) };
 }
 

package/runtime/app-render.mjs

@@ -15,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';
@@ -243,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();}
 }
 

package/runtime/app-stream-channel.mjs

@@ -12,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();
@@ -43,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() {

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/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,
     });