@thomas.f/prnext 0.1.19-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,11 +21,13 @@ 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;
 let application;
 let strictMode = true;
+const navigationStreams = new WeakMap();
 
 function loadClientModule(source) {
   if (typeof source === 'function') return source();
@@ -144,10 +146,11 @@ function NormalStyles({ css, fonts }) {
 
 function AppRoot({ model, controller, committed, url, globalErrorComponent, globalErrorCss, retentionEpoch, retentionAuthorizationEpoch }) {
   const [hydrated, setHydrated] = React.useState(false);
+  const flight = navigationStreams.get(model);
   const cache = React.useRef(null);
   if (!cache.current) cache.current = createActivityCache({ limit: controller._navigationCache?.maxEntries, ttl: controller._navigationCache?.ttlMs });
   const activityCache = React.useMemo(() => ({ cache: cache.current, epoch: retentionEpoch, authorizationEpoch: retentionAuthorizationEpoch,
-    authorizationKey: model.authorizationKey, strictAuthorization: controller._navigationCache?.authCookies !== undefined }), [retentionEpoch, retentionAuthorizationEpoch, model.authorizationKey]);
+    authorizationKey: model.authorizationKey, strictAuthorization: controller._navigationCache?.authCookies !== undefined, flight }), [retentionEpoch, retentionAuthorizationEpoch, model.authorizationKey, flight]);
   const previewDynamic = React.useCallback(() => { throw model.partialPreview.suspended; }, [model.partialPreview]);
   useLayoutEffect(() => {
     if (process.env.NODE_ENV === 'development' && model.instantDiagnostics?.length) globalThis.__PRNEXT_DEV__?.reportError(Object.assign(new Error(model.instantDiagnostics.join('\n')), { digest: 'PRNEXT_INSTANT_BLOCKING' }));
@@ -255,13 +258,17 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   // entry with the previous view's routing state on the next scroll event.
   let historyRouting = currentRouting;
   let currentModel = initialModel;
-  let committedView = { model: initialModel, routing: currentRouting, url: currentUrl.href };
-  let pendingView;
+  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;
   let nextKey = currentKey + 1;
   let navigation = 0;
-  let activeRequest, finishNavigation, finishCommit, pageHidden = false, notifyingPrefetch = false;
+  let activeRequest, finishNavigation, finishCommit, documentTimer, pageHidden = false, notifyingPrefetch = false, documentFallback = false;
   const prefetches = new Map(), scheduler = createPrefetchScheduler();
   const partialSegments = (typeof __PRNEXT_CACHE_COMPONENTS__ === 'undefined' ? cacheComponents : __PRNEXT_CACHE_COMPONENTS__) ? new Map() : null;
   let segmentBytes = 0;
@@ -278,34 +285,109 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     }
   }
 
-  function renderView(model, url, { token = navigation, canonical = true, committed } = {}) {
-    const view = { model, token };
+  function renderView(model, url, { token = navigation, canonical = true, kind = 'navigation', committed } = {}) {
+    const flight = navigationStreams.get(model), view = { model, token, kind, committed: false };
     pendingView = view;
-    startTransition(() => root.render(appView({ model, controller, url, globalErrorComponent, globalErrorCss,
+    const promote = () => {
+      if (token !== navigation || pendingView !== view || !view.committed || flight?.complete === false) return;
+      pendingView = undefined;
+      if (flight) flight.committed = undefined;
+      // 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, element, retentionEpoch: controller._retentionEpoch, authorizationEpoch: controller._authorizationEpoch };
+        developmentView = undefined;
+      }
+    };
+    if (flight) flight.committed = promote;
+    const element = appView({ model, controller, url, globalErrorComponent, globalErrorCss,
       committed: () => {
         if (token !== navigation || pendingView !== view) return;
-        pendingView = undefined;
-        // A PPR preview is authorized UI, but not the completed route model
-        // from which a later navigation should inherit its layout cache.
-        if (canonical) committedView = { model, routing: model.routing, url };
+        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;
+    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;
+      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 && 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;
   }
 
+  function fallbackDocument(url, replace = true, defer = false) {
+    // The invalidated document stays blocked until its replacement arrives.
+    // Repeated synchronous actions must neither dispatch nor start reloads.
+    if (documentFallback) return;
+    documentFallback = true;
+    navigation++;
+    activeRequest?.abort();
+    appStyleManager(document).cancel();
+    finishNavigation?.(); finishNavigation = undefined;
+    invalidatePrefetches();
+    flightTransport.clear();
+    if (controller._navigationCache?.authCookies !== undefined) document.documentElement.style.visibility = 'hidden';
+    const request = () => {
+      documentTimer = undefined;
+      if (pageHidden) return;
+      if (replace) window.location.replace(url);
+      else window.location.assign(url);
+    };
+    // An executed action must settle its promise chain before document
+    // replacement suspends the old realm. Its POST guard is already latched.
+    if (defer) documentTimer = setTimeout(request, 0);
+    else request();
+  }
+
+  function requiresAuthorizedDocument(model) {
+    if (controller._navigationCache?.authCookies === undefined) return false;
+    const identity = model?.authorizationKey;
+    // Activity entries are only part of the retained tree: shared client
+    // layouts and server layout-cache props can also belong to the old user.
+    // An unidentified static model cannot prove that HttpOnly cookies stayed
+    // the same. Cross this boundary before adopting any cached layout state.
+    return typeof identity !== 'string' || !identity || identity !== currentModel.authorizationKey ||
+      committedView.authorizationEpoch !== controller._authorizationEpoch;
+  }
+
+  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;
@@ -326,19 +408,30 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     }
     await onPartial?.(response, destination);
     let model;
-    try { model = assertModel(await createFromFetch(Promise.resolve(exported?response:await flightTransport.response(response,base)), 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;
     const rewrite = readRewriteHeader(response);
     if (rewrite) model.rewrite = rewrite;
     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,
@@ -408,15 +501,20 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
 
   function callServer(id, args) {
     if (!root) return Promise.reject(new Error('Server Actions cannot run during initial rendering'));
+    if (pageHidden || documentFallback) return Promise.reject(actionReloadError());
     const token = ++navigation;
     finishCommit?.();
     const target = new URL(window.location.href);
     saveScroll();
-    abandonPendingView();
+    const restored = abandonPendingView();
     activeRequest?.abort();
     appStyleManager(document).cancel();
     finishNavigation?.(); finishNavigation = undefined;
     activeRequest = undefined;
+    if (!restored) {
+      fallbackDocument(target.href);
+      return Promise.reject(actionReloadError());
+    }
     purgeRetainedPages();
     // Mutations are dispatched in order, including Set-Cookie effects required
     // by a subsequent action. Capture their route priority when invoked: a
@@ -427,16 +525,17 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   }
 
   async function dispatchAction(id, args, token, target) {
+    if (pageHidden || documentFallback) throw actionReloadError();
     const release = scheduler.navigation();
     try { return await performAction(id, args, token, target); } finally { release(); }
   }
 
   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;
@@ -448,6 +547,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     invalidatePrefetches();
     const temporaryReferences = createTemporaryReferenceSet();
     const body = await encodeReply(args, { temporaryReferences });
+    if (pageHidden || documentFallback) throw actionReloadError();
     const response = await fetch(target.href, {
       method: 'POST',
       headers: { ...deploymentHeaders(deploymentId), 'Next-Action': id, RSC: '1', Accept: 'text/x-component', ...(currentRouting ? { 'x-prnext-router-state': encodeURIComponent(JSON.stringify({ ...currentRouting, refresh: true })) } : {}) },
@@ -474,8 +574,21 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     };
     if (process.env.NODE_ENV === 'development') await waitForDevelopmentUpdate();
     controller._retentionEpoch++;
+    const validOutcome = model && typeof model === 'object' && (Object.hasOwn(model, 'tree') || Object.hasOwn(model, 'actionResult') || model.actionError || model.actionRedirect || model.routingInvalid);
+    if (!validOutcome) throw new Error('The Server Action response did not contain a result');
+    if (Object.hasOwn(model, 'tree') && !model.routingInvalid) assertModel(model);
+    if (requiresAuthorizedDocument(model)) {
+      // A queued action or newer navigation can supersede the render token,
+      // but cannot make an observed account change safe to ignore. Complete
+      // this one POST and block the queue before any subsequent mutation.
+      const latest = pendingNavigation?.token === navigation ? pendingNavigation : undefined;
+      const redirected = token === navigation && model.actionRedirect ? navigationUrl(model.actionRedirect.url) : undefined;
+      const destination = latest?.url || redirected?.href || window.location.href;
+      fallbackDocument(destination, latest ? latest.replace : redirected ? model.actionRedirect.type === 'replace' : true, true);
+      return outcome();
+    }
     if (model?.routingInvalid || (model?.rootLayout && currentModel.rootLayout && model.rootLayout !== currentModel.rootLayout)) {
-      if (token === navigation) window.location.replace(target.href);
+      if (token === navigation) fallbackDocument(target.href);
       return outcome();
     }
     if (model?.actionRedirect) {
@@ -497,7 +610,7 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
       currentModel = model;
       historyRouting = currentRouting;
       appStyleManager(document).handoff(model.globalError ? [] : model.css || []);
-      renderView(model, target.href, { token });
+      renderView(model, target.href, { token, kind: 'action' });
     }
     if (model?.actionError) return outcome();
     // Flight's JSON reviver removes object fields encoded as $undefined. A
@@ -508,22 +621,32 @@ 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) 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))) {
-      if (replace) window.location.replace(target.href);
-      else window.location.assign(target.href);
-      return;
+      fallbackDocument(target.href, replace);
+      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?.();
     saveScroll();
-    abandonPendingView();
+    const restored = abandonPendingView();
     activeRequest?.abort();
     appStyleManager(document).cancel();
     finishNavigation?.(); finishNavigation = undefined;
     activeRequest = undefined;
+    if (!restored) {
+      fallbackDocument(target.href, replace || pop || refresh);
+      return developmentSignal ? false : undefined;
+    }
 
     function updateHistory(destination) {
       historyRouting = currentRouting;
@@ -545,7 +668,8 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
         target.pathname === committedUrl.pathname && target.search === committedUrl.search) {
       updateHistory(target);
       if (scroll) scrollToTarget(target, savedScroll);
-      return;
+      if (pendingNavigation === intent) pendingNavigation = undefined;
+      return developmentSignal ? false : undefined;
     }
 
     const cacheKey = `${target.origin}${target.pathname}${target.search}`;
@@ -575,6 +699,12 @@ 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.
+            if (controller._navigationCache?.authCookies !== undefined) return;
             if (!preview || token !== navigation || response.headers.get('x-prnext-ppr-id') !== preview.id ||
                 (preview.model.rootLayout && currentModel.rootLayout && preview.model.rootLayout !== currentModel.rootLayout)) return;
             // Auth, middleware and rewrites ran again. A changed target or a
@@ -582,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 || []);
@@ -594,14 +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 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;
@@ -615,36 +758,59 @@ 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.
-      if (replace || pop || refresh) window.location.replace(target.href);
-      else window.location.assign(target.href);
+      fallbackDocument(target.href, replace || pop || refresh);
+      return developmentSignal ? false : undefined;
     } finally {
+      if (pendingNavigation === intent) pendingNavigation = undefined;
       if (finishNavigation === releaseNavigation) finishNavigation = undefined;
       releaseNavigation();
     }
   }
 
-  function purgeRetainedPages() {
+  function purgeRetainedPages({ synchronous = false } = {}) {
+    if (pageHidden || documentFallback) return false;
     saveScroll();
-    abandonPendingView();
+    if (!abandonPendingView()) {
+      activeRequest?.abort();
+      fallbackDocument(currentUrl.href);
+      return false;
+    }
     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;
   }
 
   const controller = {
@@ -656,13 +822,13 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
     replace: (href, options) => { void navigate(navigationUrl(href), { ...options, replace: true }); },
     refresh: () => {
       invalidatePrefetches();
-      purgeRetainedPages();
+      if (!purgeRetainedPages()) return;
       void navigate(new URL(window.location.href), { refresh: true });
     },
     back: () => { saveScroll(); window.history.back(); },
     forward: () => { saveScroll(); window.history.forward(); },
     prefetch(href, options = {}) {
-      if (pageHidden) return;
+      if (pageHidden || documentFallback) return;
       const target = navigationUrl(href);
       if (!isApplicationURL(target, window.location.origin, basePath) || isHtmlDocumentRoute(htmlOnlyRoutes, removeBasePath(target.pathname, basePath))) return;
       target.hash = '';
@@ -703,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) {
@@ -727,8 +894,22 @@ async function startApp({ deploymentId, htmlOnlyRoutes, clientModules = {}, base
   window.addEventListener('popstate', event => {
     void navigate(new URL(window.location.href), { pop: true, savedScroll: event.state?.__prnext?.scroll, savedRouting: event.state?.__prnext?.routing });
   });
-  window.addEventListener('pagehide', () => { saveScroll(); pageHidden = true; navigation++; finishCommit?.(); abandonPendingView(); activeRequest?.abort(); appStyleManager(document).cancel(); finishNavigation?.(); finishNavigation = undefined; invalidatePrefetches(); });
-  window.addEventListener('pageshow', event => { pageHidden = false; if (event.persisted) controller.refresh(); });
+  window.addEventListener('pagehide', () => {
+    saveScroll(); pageHidden = true; navigation++; finishCommit?.(); abandonPendingView();
+    clearTimeout(documentTimer); documentTimer = undefined;
+    activeRequest?.abort(); appStyleManager(document).cancel(); finishNavigation?.(); finishNavigation = undefined; invalidatePrefetches();
+    // A cached document may contain an account's shared layout state. Keep it
+    // hidden if restored from BFCache until the next document authorizes it.
+    if (controller._navigationCache?.authCookies !== undefined) document.documentElement.style.visibility = 'hidden';
+  });
+  window.addEventListener('pageshow', event => {
+    pageHidden = false;
+    if (!event.persisted) return;
+    if (controller._navigationCache?.authCookies !== undefined) {
+      documentFallback = false;
+      fallbackDocument(window.location.href);
+    } else controller.refresh();
+  });
   window.addEventListener('prnext:invalidate-navigation', () => { controller._authorizationEpoch++; controller.refresh(); });
   let scrollFrame;
   window.addEventListener('scroll', () => {
@@ -747,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);
@@ -756,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-partial.mjs

@@ -8,9 +8,10 @@ import { appContent } from './app-content.mjs';
 import { runRequestContext, currentRequest } from '../compat/headers.cjs';
 import { cachedValue, cacheGeneration, flushCacheWork } from '../compat/data-cache.cjs';
 import { partialModel, preparePartialModel } from './app-partial-model.mjs';
-import { MAX_RESPONSE_BYTES, escapeHtml } from './http.mjs';
+import { escapeHtml, MAX_RESPONSE_BYTES } from './http.mjs';
 import { fontPreloads } from './font-preload.mjs';
 import { PartialArtifactCache } from './partial-artifact-cache.mjs';
+export {partialShell} from './native-ppr.mjs';
 
 const artifacts = new Map();
 const parsedArtifacts = new PartialArtifactCache();
@@ -32,7 +33,6 @@ async function readArtifact(file) {
   }
   return value;
 }
-
 async function bytes(stream) {
   const chunks = [];
   let length = 0;
@@ -120,11 +120,3 @@ export async function partialArtifact({ request, route, manifest, filename, iden
     } finally { await flushCacheWork(context); }
   });
 }
-
-export function partialShell(artifact, route) {
-  const bootstrap = '<script>self.__PRNEXT_FLIGHT_STREAM__=self.__PRNEXT_FLIGHT_STREAM__||[];</script>' +
-    (route.client ? `<script type="module" async src="${escapeHtml(route.client)}"></script>` : '');
-  const end = artifact.shell.lastIndexOf('</body>');
-  if (end < 0 || !/<\/body><\/html>$/i.test(artifact.shell)) throw new Error('Invalid partial prerender document');
-  return artifact.shell.slice(0, end) + bootstrap + artifact.shell.slice(end);
-}

package/runtime/app-prefetch.mjs

@@ -1,6 +1,7 @@
 // Prefetch contains only prerendered segments. Request-dependent holes are
 // resolved by a fresh, authenticated navigation; they never enter this cache.
 import { PARTIAL_PREFETCH_BYTES } from './app-prefetch-constants.mjs';
+import { decodeBase64 } from '../compat/base64.cjs';
 export { PARTIAL_PREFETCH_TYPE, PARTIAL_PREFETCH_BYTES, PARTIAL_PREFETCH_CACHE_BYTES } from './app-prefetch-constants.mjs';
 
 export async function readPartialPrefetch(response) {
@@ -27,7 +28,6 @@ export async function readPartialPrefetch(response) {
 }
 
 export function partialFlightStream(base64) {
-  const binary = atob(base64);
-  const bytes = Uint8Array.from(binary, character => character.charCodeAt(0));
+  const bytes = decodeBase64(base64);
   return new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); } });
 }