@wular/pnext 0.0.24 → 0.1.1

package/src/render/renderer.ts

@@ -80,6 +80,7 @@ import {
   currentPrerenderScope,
   hangingPromise,
   isCachedComponent,
+  isCsrBailoutPrerender,
   isHangingPromise,
   isPrerendering,
   isPostpone,
@@ -89,6 +90,7 @@ import {
   markRuntimeApiOnAwait,
   PostponeError,
   runInPrerender,
+  runWithCsrBailout,
   runWithPrerenderDeterminism,
   runWithRuntimePrefetchSyncIoAbort,
   runWithTaskBoundaryArmed,
@@ -188,6 +190,7 @@ import {
   type SlotContext,
 } from './slots'
 import {
+  CsrBailoutContext,
   LayoutSegmentContext,
   RouteParamsContext,
   type LayoutSegmentSnapshot,
@@ -224,6 +227,34 @@ const LOADING_THROUGH_PROP = '__pnextLoadingThrough'
 const LOADING_DEPTH_PROP = '__pnextLoadingDepth'
 const LOADING_DEPTH_ATTRIBUTE = 'data-pnext-loading-depth'
 
+// The inline-suspense wire form carries no vnode props: preact writes the fallback between
+// bare `<!--$s:ID-->` comments, so a loading.js boundary there cannot prove itself to the
+// navigation runtime and its fallback never paints (searchparams-reuse-loading "should re-use
+// the prefetched loading state"). Lead the fallback with this empty element instead;
+// `anchorInlineSuspenseHoles` lifts its attribute onto the hole and drops it.
+const LOADING_DEPTH_TAG = 'pnext-loading-depth'
+
+/** Lead a loading.js fallback with its depth marker. Lifted onto the hole, scrubbed otherwise. */
+function markInlineLoadingFallback(
+  fallback: ComponentChildren,
+  depth: number | undefined,
+): ComponentChildren {
+  if (depth === undefined) return fallback
+  return h(
+    Fragment,
+    null,
+    h(LOADING_DEPTH_TAG, { [LOADING_DEPTH_ATTRIBUTE]: String(depth) }),
+    fallback,
+  )
+}
+
+/** Drop depth markers no hole claimed - the marker wire form carries the attribute itself. */
+function dropLoadingDepthMarkers(html: string): string {
+  return html.includes(LOADING_DEPTH_TAG)
+    ? html.replace(new RegExp(`<${LOADING_DEPTH_TAG}[^>]*></${LOADING_DEPTH_TAG}>`, 'g'), '')
+    : html
+}
+
 /** The `data-pnext-loading-depth` attributes for a Suspense vnode, if any. */
 function loadingDepthAttributes(props: unknown): Record<string, string> {
   const depth = (props as Record<string, unknown>)[LOADING_DEPTH_PROP]
@@ -543,6 +574,8 @@ interface LayoutRender {
   tree: ComponentChildren
   metadata: MetadataEntry[]
   runtimeMetadata: boolean
+  /** A layout's `generateMetadata` awaited real I/O, so the shell would have flushed without it. */
+  metadataMissedFlush: boolean
   slotMatches: ResolvedSlotMatch[]
   viewport: Viewport[]
   documentLayoutFile?: string
@@ -584,6 +617,8 @@ interface ResolveState {
   clientComponents: ClientComponentMap
   clientReferences: ClientReferenceMap
   partial?: PartialState
+  /** Nearest Suspense fallback for a static client-rendering bailout. */
+  csrBailoutFallback?: ComponentChildren
   /**
    * Static-skeleton pass for a postponed boundary: a server component that
    * postpones resolves to null instead of failing the pass, so the boundary's
@@ -860,7 +895,7 @@ function renderDocumentStart(page: DocumentPage) {
     ${page.clientScript}
     ${page.deferredScripts ?? ''}
     ${page.devScript}`
-  return stampDocumentNonce(html, page.nonce)
+  return dropLoadingDepthMarkers(stampDocumentNonce(html, page.nonce))
 }
 
 // CSP nonce stamping. A nonce on the request's Content-Security-Policy header is applied,
@@ -1489,16 +1524,24 @@ export async function renderPageWithStatus(
     () =>
       runWithFontScope(() =>
         runWithCacheScope(async () => {
-          const page = await pageRender(options, false)
-          const location =
-            page.headers && !(page.headers instanceof Headers) && !Array.isArray(page.headers)
-              ? page.headers.location
-              : undefined
-          return {
-            html: renderDocument(page),
-            status: page.status ?? 200,
-            ...(location ? { location } : {}),
+          const render = async () => {
+            const page = await pageRender(options, false)
+            const location =
+              page.headers && !(page.headers instanceof Headers) && !Array.isArray(page.headers)
+                ? page.headers.location
+                : undefined
+            return {
+              html: renderDocument(page),
+              status: page.status ?? 200,
+              ...(location ? { location } : {}),
+            }
           }
+          const staticGeneration =
+            options.route.segmentConfig?.dynamic !== 'force-static' &&
+            // eslint-disable-next-line turbo/no-undeclared-env-vars
+            process.env.NEXT_PHASE === 'phase-production-build'
+          if (!staticGeneration) return render()
+          return runWithCsrBailout(render)
         }),
       ),
     options.params ?? {},
@@ -1601,7 +1644,8 @@ export async function renderPageResponse(options: RenderOptions) {
             canStreamRoute(options) && !isDomBotRequest(options),
           )
           if (page.headers) {
-            return new Response(null, {
+            const location = readLocationHeader(page.headers)
+            return new Response(method === 'HEAD' ? null : (location ?? null), {
               status: page.status ?? 307,
               headers: page.headers,
             })
@@ -2950,11 +2994,12 @@ async function pageRender(options: RenderOptions, stream: boolean): Promise<Page
     const prebuiltPageMetadata = pageFile ? options.staticModuleMetadata?.[pageFile] : undefined
     const pageMetadata = pageModule
       ? (parent: Metadata) =>
-          (metadataExtensions.readModuleMetadata
-            ? metadataExtensions.readModuleMetadata(pageModuleRecord!, props, parent, pageFile)
-            : prebuiltPageMetadata?.metadata
-              ? Promise.resolve(prebuiltPageMetadata.metadata)
-              : readModuleMetadata(pageModule)
+          trackMetadataRedirect(
+            metadataExtensions.readModuleMetadata
+              ? metadataExtensions.readModuleMetadata(pageModuleRecord!, props, parent, pageFile)
+              : prebuiltPageMetadata?.metadata
+                ? Promise.resolve(prebuiltPageMetadata.metadata)
+                : readModuleMetadata(pageModule),
           ).then(meta => meta ?? {})
       : {}
     const viewportStart = profileRenderMark(profile)
@@ -3011,7 +3056,11 @@ async function pageRender(options: RenderOptions, stream: boolean): Promise<Page
     // static artifact with no `postponed`
     // (cache-components-errors "notFound() with dynamic ...").
     if (options.runtimeRegen && (isRedirectError(error) || isNotFoundError(error))) throw error
-    if (isRedirectError(error)) return renderRedirectPage(error.location, error.status)
+    if (isRedirectError(error)) {
+      return shouldRenderDocumentRedirect(options, error)
+        ? renderDocumentRedirect(options, stream, error.location, error.status)
+        : renderRedirectPage(error.location, error.status)
+    }
     if (isNotFoundError(error)) return renderNotFoundPage(options, stream)
     // authInterrupts (COMPAT-ONLY): forbidden()/unauthorized() render their own
     // convention boundary with a dedicated status. They are gated behind
@@ -3314,6 +3363,67 @@ function renderRedirectPage(location: string, status: number): PageRender {
   }
 }
 
+function readLocationHeader(headers: HeadersInit): string | null {
+  if (headers instanceof Headers) return headers.get('location')
+  if (Array.isArray(headers)) return new Headers(headers).get('location')
+  return headers.location ?? null
+}
+
+/**
+ * Redirect errors that escaped a `generateMetadata` call. Next renders metadata inside a
+ * Suspense boundary, so a redirect thrown there resolves AFTER the response status is fixed:
+ * the document is a 200 carrying the meta-refresh envelope, whatever the route's mode
+ * (metadata-navigation "should support redirect in generateMetadata").
+ */
+const metadataRedirects = new WeakSet<object>()
+
+function noteMetadataRedirect(error: unknown): void {
+  if (isRedirectError(error) && typeof error === 'object') metadataRedirects.add(error)
+}
+
+/**
+ * Tag a metadata promise's redirect rejection. Observes the SAME promise rather than chaining
+ * off it: an extra microtask here delays metadata resolution by a tick, which is enough to flip
+ * the head-vs-body streaming decision (metadata-streaming "should delay the metadata render to
+ * body").
+ */
+function trackMetadataRedirect<T>(promise: Promise<T>): Promise<T> {
+  void promise.catch(noteMetadataRedirect)
+  return promise
+}
+
+function shouldRenderDocumentRedirect(options: RenderOptions, error: unknown): boolean {
+  if (!nextCompatEnabled(options.config)) return false
+  const request = options.request
+  if (request?.method.toUpperCase() !== 'GET') return false
+  if (request.headers.get('rsc') === '1') return false
+  // A page/layout redirect on a dynamic route still answers with a real 307 - the render
+  // throws before anything is flushed. Metadata is the exception: it is suspended, so its
+  // redirect lands after the status - unless this render BLOCKS on metadata (html-limited
+  // bot), where the redirect is a real 307 again.
+  if (options.route.mode !== 'dynamic') return true
+  return metadataRedirects.has(error as object) && !isHtmlLimitedBotRequest(options)
+}
+
+async function renderDocumentRedirect(
+  options: RenderOptions,
+  stream: boolean,
+  location: string,
+  status: number,
+): Promise<PageRender> {
+  const page = await renderTreeOrFallback(options, h('div', pageRootProps), stream, {})
+  const seconds = status === 308 ? 0 : 1
+  const meta = `<meta id="__next-page-redirect" http-equiv="refresh" content="${seconds};url=${escapeHtml(location)}"/>`
+  const digest = `NEXT_REDIRECT;replace;${location};${status};`
+  const flight = JSON.stringify(`E${JSON.stringify({ digest })}`).replace(/</g, '\\u003c')
+  return {
+    ...page,
+    head: [page.head, meta].filter(Boolean).join('\n    '),
+    routeScript: `${page.routeScript}<script>self.__next_f=self.__next_f||[]</script><script>self.__next_f.push([1,${flight}])</script>`,
+    status: 200,
+  }
+}
+
 async function resolveSelectedSlotMetadata(
   options: RenderOptions,
   matches: ResolvedSlotMatch[],
@@ -3387,7 +3497,9 @@ async function renderTreeInFrame(
     if (options.dev && lazyClientReferencePreload()) {
       // Lazy mode: the preload keeps warming in the background; the render
       // blocks only on the references it reaches (ensureClientComponent),
-      // seeded with a warm route's settled marking.
+      // seeded with a warm route's settled marking. Soft navigations receive
+      // only that settled snapshot from preloadClientReferences; discovery
+      // below joins the references present in this render instead of the route.
       options.clientComponentsPreload.catch(() => undefined)
       const settled = settledMarkedReferences.get(options.route.id)
       if (settled) mergeClientComponents(clientComponents, settled)
@@ -3482,7 +3594,7 @@ async function renderTreeInFrame(
     : { entries: [], runtime: false }
   const runtimeMetadata =
     layoutRender.runtimeMetadata || Boolean(extra.runtimePageMetadata) || slotMetadata.runtime
-  const runtimeMetadataInBody = shouldRenderRuntimeMetadataInBody(options, runtimeMetadata)
+  const metadataMayStream = shouldRenderRuntimeMetadataInBody(options, runtimeMetadata)
   let metadataNavigationHtml = ''
   let resolvedPageMetadata: Metadata
   const lateChunks: Promise<string>[] = []
@@ -3496,6 +3608,22 @@ async function renderTreeInFrame(
   // Captured explicitly: the page body already populated the render's cache() scope, and a deferred
   // generateMetadata must reuse it or its cache()-wrapped values drift from what the body rendered.
   const runInCacheScope = captureCacheScope()
+  // WHERE the tags land. Next renders metadata inside a Suspense in the body and React hoists
+  // whatever resolved before the shell flushed into the head - so FAST metadata reads as a head
+  // render and only metadata that misses the flush stays below it (conformance "metadata body
+  // placement matches Next" vs metadata-streaming "should delay the metadata render to body").
+  // A router payload has no head to hoist into, so it always rides the body.
+  const navMetadataRender =
+    Boolean(options.nav?.soft) || options.request?.headers.get('rsc') === '1'
+  const startedPageMetadata =
+    metadataMayStream && !navMetadataRender && typeof pageMetadata === 'function'
+      ? runInCacheScope(() => pageMetadata(mergeMetadataEntries(layoutRender.metadata)))
+      : undefined
+  const runtimeMetadataInBody =
+    metadataMayStream &&
+    (navMetadataRender ||
+      layoutRender.metadataMissedFlush ||
+      (startedPageMetadata ? !(await settlesBeforeFlush(startedPageMetadata)) : false))
   const pendingPageMetadata =
     typeof pageMetadata === 'function' &&
     deferrableNavigationMetadata(options, runtimeMetadataInBody, stream)
@@ -3506,21 +3634,37 @@ async function renderTreeInFrame(
   try {
     resolvedPageMetadata = pendingPageMetadata
       ? {}
-      : typeof pageMetadata === 'function'
-        ? await pageMetadata(mergeMetadataEntries(layoutRender.metadata))
-        : pageMetadata
+      : startedPageMetadata
+        ? await startedPageMetadata
+        : typeof pageMetadata === 'function'
+          ? await pageMetadata(mergeMetadataEntries(layoutRender.metadata))
+          : pageMetadata
   } catch (error) {
     if (options.partial?.mode === 'build' && isPostpone(error)) {
       options.partial.metadataDynamic = true
       resolvedPageMetadata = {}
-    } else if (!runtimeMetadataInBody) {
+    } else if (
+      options.request &&
+      nextCompatEnabled(options.config) &&
+      isNotFoundError(error) &&
+      !isHtmlLimitedBotRequest(options)
+    ) {
+      // Streamed metadata resolves after the status is sent, so notFound() lands as a client
+      // boundary on a 200. A bot's metadata BLOCKS, so its notFound() is a real 404
+      // (metadata-streaming "blocking 404 response status when html limited bots").
+      return renderNotFoundPage(options, stream, { status: 200, nextFlightText: true })
+    } else if (!metadataMayStream) {
+      // Blocking metadata (an html-limited bot, a build prerender): its control flow still owns
+      // the whole response.
       throw error
     } else if (isNotFoundError(error)) {
       return renderNotFoundPage(options, stream, { status: 200, nextFlightText: true })
-    } else if (isRedirectError(error)) {
+    } else if (isRedirectError(error) && runtimeMetadataInBody) {
       metadataNavigationHtml = metadataRedirectHtml(error.location, error.status)
       resolvedPageMetadata = {}
     } else {
+      // Head-placed metadata carries no body chunk to hold the envelope; the document-level
+      // handler emits it (200 + meta refresh, or a real 307 for a blocking bot render).
       throw error
     }
   }
@@ -3595,7 +3739,7 @@ async function renderTreeInFrame(
       stylesheets: [],
     })
     const iconLinks =
-      extra.runtimePageMetadata && pageMeta.icons !== undefined
+      streamRuntimeMetadataInBody && extra.runtimePageMetadata && pageMeta.icons !== undefined
         ? [
             headLinks(
               {
@@ -3896,8 +4040,26 @@ function deferrableNavigationMetadata(
   return !getRouterProtocolExtensions().shellOnlyRequest(request, options.route)
 }
 
+/**
+ * True when `promise` settles without waiting on I/O - a streaming server would still be building
+ * the shell, so React would hoist the resolved tags into the head. A timer/network await loses the
+ * race and the tags land in the body instead.
+ */
+function settlesBeforeFlush(promise: Promise<unknown>): Promise<boolean> {
+  return Promise.race([
+    promise.then(
+      () => true,
+      () => true,
+    ),
+    new Promise<boolean>(resolve => setTimeout(() => resolve(false), 0)),
+  ])
+}
+
 function shouldRenderRuntimeMetadataInBody(options: RenderOptions, runtimeMetadata: boolean) {
   if (!runtimeMetadata) return false
+  // Placement is a function of the USER AGENT alone (Next's shouldServeStreamingMetadata): a
+  // document GET from a browser streams its metadata into the body exactly like an RSC
+  // navigation does, and only an html-limited bot gets the blocking head render.
   if (!options.dev && options.route.mode !== 'dynamic') return false
   return Boolean(
     getActiveMetadataExtensions(options.config).shouldRenderMetadataInBody?.({
@@ -4031,8 +4193,10 @@ async function addDiscoveredClientReferences(
   const discovered = new Map<string, ClientReference>()
   collectClientReferences(tree, discovered)
   // Lazy mode: register ids only; ensureClientComponent imports the references
-  // the render actually reaches at emission time.
-  const lazy = Boolean(options.dev) && lazyClientReferencePreload()
+  // the render actually reaches at emission time. A dev soft navigation is the
+  // exception: compile the references in its rendered tree before shell emission
+  // so application Suspense cannot expose a compile-only fallback.
+  const lazy = Boolean(options.dev) && lazyClientReferencePreload() && !options.nav?.soft
   await Promise.all(
     [...discovered.values()].map(async reference => {
       const resolved = references.get(reference.id) ?? reference
@@ -4653,6 +4817,13 @@ function preloadClientReferences(options: RenderOptions, profile: RenderProfile
     markedReferences.clear()
     settledMarkedReferences.clear()
   }
+  // A dev soft navigation must not join or start the whole route marking pass:
+  // its response latency should scale with references in the rendered tree,
+  // which addDiscoveredClientReferences compiles before shell emission. Reuse a
+  // warm snapshot when available; otherwise discovery starts from an empty map.
+  if (lazyClientReferencePreload() && options.nav?.soft) {
+    return Promise.resolve(settledMarkedReferences.get(options.route.id) ?? new Map())
+  }
   const cached = markedReferences.get(options.route.id)
   if (cached) return cached
   const marking = profileRenderStep(profile, 'preload client references', () =>
@@ -4699,6 +4870,7 @@ function ClientIsland(
     __pnextParamsScope?: RouteParamsSnapshot
     __pnextTemplate?: boolean
     __pnextSkipSsr?: boolean
+    __pnextCsrFallback?: ComponentChildren
   },
 ) {
   const {
@@ -4709,6 +4881,7 @@ function ClientIsland(
     __pnextParamsScope,
     __pnextTemplate,
     __pnextSkipSsr,
+    __pnextCsrFallback,
     children,
     ref: _ref,
     ...componentProps
@@ -4805,6 +4978,9 @@ function ClientIsland(
       island,
     ) as unknown as typeof island
   }
+  if (__pnextCsrFallback !== undefined) {
+    island = h(CsrBailoutContext.Provider, { value: true }, island) as unknown as typeof island
+  }
   const fallbackChildren =
     staticChildren !== undefined && plainChildren === undefined
       ? h(
@@ -4823,7 +4999,12 @@ function ClientIsland(
       fallbackChildren !== undefined ? ([island, fallbackChildren] as ComponentChildren) : island,
     )
   }
-  return h(IslandBoundary, { islandProps, island, fallbackChildren })
+  return h(IslandBoundary, {
+    islandProps,
+    island,
+    fallbackChildren,
+    csrFallback: __pnextCsrFallback,
+  })
 }
 
 // Marks the island's static-children wrapper as rendered when the component
@@ -4854,6 +5035,7 @@ interface IslandBoundaryProps {
   islandProps: Record<string, unknown>
   island: ComponentChildren
   fallbackChildren?: ComponentChildren
+  csrFallback?: ComponentChildren
 }
 
 // Per-island SSR error boundary. Normally renders the island's server output inside its
@@ -4877,6 +5059,13 @@ class IslandBoundary extends Component<IslandBoundaryProps, { failed: boolean; e
 
   render(props: IslandBoundaryProps, state: { failed: boolean; error: unknown }) {
     if (state.failed) {
+      if (isPostpone(state.error) && props.csrFallback !== undefined) {
+        return h(
+          'pnext-client',
+          { ...props.islandProps, 'data-pnext-ssr-failed': '' },
+          props.csrFallback,
+        )
+      }
       // Propagate control-flow signals to the page-render pipeline so a
       // client-component redirect() during (pre)render becomes a 307 instead of
       // being swallowed into a 200 `data-pnext-ssr-failed` placeholder.
@@ -5055,6 +5244,10 @@ async function resolveServerTree(node: unknown, state: ResolveState): Promise<Co
 
   if (isSuspenseVNode(node)) {
     if (state.partial) return resolvePartialSuspense(node, state, state.partial)
+    if (isCsrBailoutPrerender()) {
+      const fallback = await resolveServerTree(node.props.fallback, state)
+      return resolveServerTree(node.props.children, { ...state, csrBailoutFallback: fallback })
+    }
     return resolveServerTree(node.props.children, state)
   }
 
@@ -6238,6 +6431,7 @@ function clientIslandVNode(
       __pnextParamsScope: currentParamsSnapshot(),
       __pnextSkipSsr:
         state.partial?.mode === 'build' && clientReferenceRequiresRuntime(resolvedReference),
+      __pnextCsrFallback: state.csrBailoutFallback,
     },
     children,
   )
@@ -6577,6 +6771,7 @@ async function readRenderModuleMetadata(
       options.partial.metadataDynamic = true
       return undefined
     }
+    noteMetadataRedirect(error)
     throw error
   }
 }
@@ -6747,13 +6942,25 @@ async function renderSuspendingStreamShell(
 // keys off this element instead. `display:contents` keeps it byte-neutral in
 // layout, and it is adopted as the island's static children on hydration.
 function anchorInlineSuspenseHoles(html: string): string {
-  return html
-    .replace(
-      /<!--\$s:([^>]+?)-->/g,
-      (_match, id: string) =>
-        `<pnext-hole data-pnext-hole="${escapeHtml(id)}" style="display:contents">`,
-    )
-    .replace(/<!--\/\$s:[^>]+?-->/g, '</pnext-hole>')
+  return (
+    html
+      .replace(
+        /<!--\$s:([^>]+?)-->/g,
+        (_match, id: string) =>
+          `<pnext-hole data-pnext-hole="${escapeHtml(id)}" style="display:contents">`,
+      )
+      .replace(/<!--\/\$s:[^>]+?-->/g, '</pnext-hole>')
+      // A loading.js fallback leads with its depth marker (markInlineLoadingFallback): lift it
+      // onto the hole, which is the only wire form the runtime can read attributes from.
+      .replace(
+        new RegExp(
+          `(<pnext-hole data-pnext-hole="[^"]*")( style="display:contents">)<${LOADING_DEPTH_TAG} ${LOADING_DEPTH_ATTRIBUTE}="(\\d+)"></${LOADING_DEPTH_TAG}>`,
+          'g',
+        ),
+        (_match, open: string, close: string, depth: string) =>
+          `${open} ${LOADING_DEPTH_ATTRIBUTE}="${depth}"${close}`,
+      )
+  )
 }
 
 export function clientSuspenseRefreshScript(nonce: string | undefined) {
@@ -6794,7 +7001,11 @@ function unwrapUnusedPageSlot(html: string, mode: PageSlotMarkerMode): string {
     return html.replace(/<!--pnext-page:[^>]*-->/, '<!--pnext-page:-->')
   }
   const slot = pageSlotSpan(html)
-  return slot ? html.slice(0, slot.start) + slot.children + html.slice(slot.end) : html
+  if (!slot) return html
+  // `keep` leaves the empty anchors a soft navigation grafts a kept layout's next page between.
+  const children =
+    mode === 'keep' ? `<!--pnext-page:-->${slot.children}<!--/pnext-page-->` : slot.children
+  return html.slice(0, slot.start) + children + html.slice(slot.end)
 }
 
 function serializeNeutralClientIslands(html: string) {
@@ -6814,6 +7025,12 @@ function serializeNeutralClientIslands(html: string) {
           (_tag, attributes: string) => `<!--pnext-client:${encodeIslandMarker(attributes)}-->`,
         )
         .replace(/<\/pnext-client>/g, '<!--/pnext-client-->')
+        .replace(
+          /<pnext-static-children\b([^>]*)>/g,
+          (_tag, attributes: string) =>
+            `<!--pnext-static-children:${encodeIslandMarker(attributes)}-->`,
+        )
+        .replace(/<\/pnext-static-children>/g, '<!--/pnext-static-children-->')
     })
     .join('')
   return neutralizePageSlot(islands)
@@ -6912,7 +7129,10 @@ export function clientIslandMarkerBootstrapSource(mode: PageSlotMarkerMode = 'ma
   // server `<p>`, say), by climbing out of the start marker's parent instead of
   // giving up on a sibling-only scan. Mirrors islandMarkerRange in router.ts.
   const range = `let a=[],n=null,y=s;for(;;){n=y.nextSibling;while(!n){const p=y.parentNode;if(!p||p===document.documentElement||p===document)break;y=p;n=y.nextSibling}if(!n)break;if(n.nodeType===8&&n.data==='/'+k)break;a.push(n);y=n}if(!n||n.nodeType!==8||n.data!=='/'+k)continue;const f=a[0];if(f&&f.parentNode!==s.parentNode){f.parentNode.insertBefore(e,f);s.remove()}else{s.replaceWith(e)}for(const x of a)e.append(x);n.remove()`
-  return `(()=>{window.__PNEXT_MATERIALIZE_CLIENT_ISLANDS__=r=>{const c=[];const w=document.createTreeWalker(r,NodeFilter.SHOW_COMMENT);for(;w.nextNode();)c.push(w.currentNode);for(const s of c.reverse()){if(s.data==='$s'||s.data==='/$s'){s.remove();continue}const m=/^(pnext-client(?:-after)?|pnext-page):([^>]*)$/.exec(s.data);if(!m||!s.parentNode)continue;${skipPage}const k=m[1]==='pnext-client-after'?'pnext-client':m[1],d=document.createElement('div'),q=k==='pnext-page'?'div':'pnext-client';d.innerHTML='<'+q+' '+m[2]+'></'+q+'>';const e=d.firstElementChild;if(m[1]==='pnext-client-after'){let a=s.previousSibling;while(a&&!(a.nodeType===8&&!a.data.trim()))a=a.previousSibling;if(!a)continue;let n=a.nextSibling;while(n&&n!==s){const x=n;n=n.nextSibling;e.append(x)}s.replaceWith(e);continue}${range}}};window.__PNEXT_MATERIALIZE_CLIENT_ISLANDS__(document)})()`
+  // This script runs after the server shell markup and before any client entry can hydrate it.
+  // Capture once, then materialize marker ranges. A promotion script that raced ahead keeps its
+  // stricter pre-promotion snapshot through the same first-writer-wins guard.
+  return `(function(){let W=window;W.__PNEXT_SHELL_HTML__||="<!doctype html>"+document.documentElement.outerHTML;Object.defineProperty(W,"__PNEXT_SHELL_HTML__",{writable:false});(W.__PNEXT_MATERIALIZE_CLIENT_ISLANDS__=r=>{let c=[],w=document.createTreeWalker(r,128);for(;w.nextNode();)c.push(w.currentNode);for(let s of c.reverse()){if(s.data==='$s'||s.data==='/$s'){s.remove();continue}let m=/^(pnext-client(?:-after)?|pnext-static-children|pnext-page):([^>]*)$/.exec(s.data);if(!m||!s.parentNode)continue;${skipPage}let k=m[1]==='pnext-client-after'?'pnext-client':m[1],d=document.createElement('div'),q=k==='pnext-page'?'div':k;d.innerHTML='<'+q+' '+m[2]+'></'+q+'>';let e=d.firstElementChild;if(m[1]==='pnext-client-after'){let a=s.previousSibling;while(a&&!(a.nodeType===8&&!a.data.trim()))a=a.previousSibling;if(!a)continue;let n=a.nextSibling;while(n&&n!==s){let x=n;n=n.nextSibling;e.append(x)}s.replaceWith(e);continue}${range}}})(document)})()`
 }
 
 // notFound() thrown inside a streamed Suspense boundary: render the nearest not-found convention
@@ -7039,9 +7259,9 @@ function streamErrorDocumentScript(
 // resolve to - and delete - whatever innocent node now precedes the script.
 const PROMO_RUNTIME =
   'function(){' +
-  // Stash the PRE-PROMOTION shell exactly once, before any streamed chunk has
-  // replaced its fallback. This runtime is constructed lazily by the FIRST
-  // promotion script, so the parser has seen the shell and nothing beyond it.
+  // Stash the PRE-PROMOTION shell before any streamed chunk has replaced its fallback. The document
+  // bootstrap normally wins first; when a fast continuation wins this race instead, retain its
+  // stricter pre-promotion copy and let the document bootstrap preserve it.
   //
   // A hard load has no other way back to its static stage: the router seeds its
   // caches from the LIVE document at the load event, by which time every
@@ -7049,7 +7269,7 @@ const PROMO_RUNTIME =
   // indistinguishable from a complete static prerender. Recording THAT as the
   // route's static stage would hand a later navigation resolved dynamic content;
   // recording nothing (today) leaves a PPR route with no cached static stage at
-  // all after a hard load. See client/router/index.ts preHydrationShell.
+  // all after a hard load. See client/router/runtime.ts preHydrationShell.
   'try{window.__PNEXT_SHELL_HTML__="<!doctype html>"+document.documentElement.outerHTML;}catch(e){}' +
   'var P={};' +
   // Group a node's children by the `<!--$ps:k-->…<!--/$ps:k-->` slot markers the
@@ -7064,6 +7284,10 @@ const PROMO_RUNTIME =
   'if(!t){delete P[i];return true;}' +
   "var e=document.querySelector('pnext-suspense[data-pnext-suspense=\"'+i+'\"]');" +
   'if(!e){P[i]=1;return false;}' +
+  // A boundary inside a client island: this promotion rewrites DOM the island's mounted
+  // preact tree adopted at hydration, which still names the fallback. Mark the root so the
+  // next graft rebuilds it instead of diffing against a node that has left the document.
+  'var ci=e.closest?e.closest("pnext-client[data-pnext-client]"):null;if(ci)ci.__pnextStreamGrafted=1;' +
   'var f=document.createDocumentFragment();' +
   // Slot-granular chunk: weave the shell template's build-time slots and the
   // chunk's request-time slots back into their original order, so a static
@@ -7106,6 +7330,7 @@ async function applyLayouts(
   let tree = children
   const metadata: MetadataEntry[] = []
   let runtimeMetadata = false
+  let metadataMissedFlush = false
   const viewport: Viewport[] = []
   const layoutProps = createPageProps(options)
   const layouts: LoadedLayout[] = []
@@ -7225,7 +7450,7 @@ async function applyLayouts(
       const layoutModuleRecord = layoutModule as Record<string, unknown>
       runtimeMetadata ||= Boolean(metadataExtensions.hasRuntimeMetadata?.(layoutModuleRecord))
       const prebuiltLayoutMetadata = options.staticModuleMetadata?.[layoutPath]
-      const layoutMetadata = await readRenderModuleMetadata(
+      const layoutMetadataPromise = readRenderModuleMetadata(
         options,
         layoutModuleRecord,
         layoutProps,
@@ -7233,6 +7458,10 @@ async function applyLayouts(
         layoutPath,
         prebuiltLayoutMetadata?.metadata,
       )
+      // Same head-vs-body race the page metadata runs (see renderTreeInFrame): a layout's slow
+      // generateMetadata streams into the body too (metadata-streaming-parallel-routes).
+      metadataMissedFlush ||= !(await settlesBeforeFlush(layoutMetadataPromise))
+      const layoutMetadata = await layoutMetadataPromise
       if (layoutMetadata) {
         const dir = dirname(layoutPath)
         metadata.push({
@@ -7291,7 +7520,7 @@ async function applyLayouts(
       wrapped = h(
         Suspense,
         {
-          fallback,
+          fallback: markInlineLoadingFallback(fallback, depth),
           ...(through ? { [LOADING_THROUGH_PROP]: true } : {}),
           ...(depth === undefined ? {} : { [LOADING_DEPTH_PROP]: depth }),
         },
@@ -7450,6 +7679,7 @@ async function applyLayouts(
     tree,
     metadata,
     runtimeMetadata,
+    metadataMissedFlush,
     slotMatches: slotContext.matches,
     viewport,
     documentLayoutFile,

package/src/request/context.ts

@@ -159,7 +159,6 @@ export function flushWorkUnitOnClose(
   signal?: AbortSignal,
 ): Response {
   if (!unit) return response
-  if (signal) signal.addEventListener('abort', () => flushWorkUnit(unit), { once: true })
   if (!response.body) {
     flushWorkUnit(unit)
     return response
@@ -172,16 +171,38 @@ export function flushWorkUnitOnClose(
     flushWorkUnit(unit)
     return response
   }
-  const observed = response.body.pipeThrough(
-    new TransformStream({
-      transform(chunk, controller) {
-        controller.enqueue(chunk)
-      },
-      flush() {
-        flushWorkUnit(unit)
-      },
-    }),
-  )
+  const reader = response.body.getReader()
+  const settle = () => {
+    signal?.removeEventListener('abort', settle)
+    flushWorkUnit(unit)
+  }
+  if (signal?.aborted) settle()
+  else signal?.addEventListener('abort', settle, { once: true })
+  // Bun cancels a response body when its client disconnects. A TransformStream
+  // observes normal EOF through flush(), but cancellation bypasses flush and
+  // only propagates upstream. Own the outer stream so both terminal paths
+  // settle the request work unit, even when Request.signal is not the original
+  // socket-owned signal after request rewriting.
+  const observed = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const chunk = await reader.read()
+        if (chunk.done) {
+          settle()
+          controller.close()
+        } else {
+          controller.enqueue(chunk.value)
+        }
+      } catch (error) {
+        settle()
+        controller.error(error)
+      }
+    },
+    cancel(reason) {
+      settle()
+      return reader.cancel(reason)
+    },
+  })
   return new Response(observed, {
     status: response.status,
     statusText: response.statusText,