@wular/pnext 0.0.18 → 0.0.20

package/src/render/renderer.ts

@@ -54,7 +54,16 @@ import {
   reportRequestError,
   type SerializedError,
 } from '../extensions'
-import { globalCssHref, registerCssRuntime, routeCssHref, withAssetPrefix } from '../css/build'
+import {
+  assetHref,
+  emitFontCssStylesheet,
+  emittedAssetName,
+  globalCssHref,
+  registerCssRuntime,
+  routeCssAssetNames,
+  routeCssHref,
+  withAssetPrefix,
+} from '../css/build'
 import { dynamicReferenceSymbol, type DynamicReference } from '../api/dynamic'
 import {
   isForbiddenError,
@@ -92,6 +101,7 @@ import {
   findConventionFiles,
   findGlobalError,
   findLayouts,
+  serverActionsUnsupportedMessage,
 } from '../routing/routes'
 import { matchSegments, pathnameSegments, slotDirectoriesIn } from '../routing/slots'
 import { getRequestRuntime } from '../routing/request-environment'
@@ -119,10 +129,12 @@ import {
 } from '../utils/dev-profile'
 import {
   applyStaticMetadata,
+  assetLinkGroups,
   coerceString,
   headLinks,
   metadataIconLinks,
   metadataContext,
+  metadataOnlyLinks,
   metadataTags,
   mergeMetadataEntries,
   mergeViewport,
@@ -136,7 +148,15 @@ import {
   type ViewportExport,
   type MetadataEntry,
 } from './metadata'
-import { clearResourceHints, takeResourceHints } from './resource-hints'
+import {
+  clearRenderBuffer,
+  clearResourceHints,
+  newRenderBufferFrame,
+  RENDER_BUFFER_SCOPE,
+  takeRenderBuffer,
+  takeResourceHints,
+  type RenderBufferFrame,
+} from './resource-hints'
 import {
   staticMetadataForPath,
   staticMetadataForPathFromFiles,
@@ -230,6 +250,9 @@ function runWithFontScope<T>(callback: () => T): T {
 
 const rawTextRenderingInstalled = Symbol.for('pnext.raw-text-rendering-installed')
 const actionSerializeScope = new AsyncLocalStorage<ActionSerializeState>()
+// Owns the per-render buffer frame the compat bundles write into; see render/resource-hints.
+const renderBufferScope = ((globalThis as Record<PropertyKey, unknown>)[RENDER_BUFFER_SCOPE] ??=
+  new AsyncLocalStorage<RenderBufferFrame>()) as AsyncLocalStorage<RenderBufferFrame>
 /** True while a render that SUSPENDS in place is running; see installRawTextRendering. */
 const suspendingStreamScope = new AsyncLocalStorage<boolean>()
 
@@ -402,7 +425,6 @@ interface RenderOptions {
   staticMetadataFiles?: StaticMetadataFile[]
   staticModuleMetadata?: Record<string, StaticModuleMetadata>
   staticRouteMetadata?: Record<string, StaticMetadataForPath>
-  resolveDynamicMetadataRoutes?: boolean
   status?: number
   partial?: PartialState
   /**
@@ -506,6 +528,8 @@ interface PageRender {
   fontCss: string
   bodyIconLinks?: string
   compatBodyScript?: string
+  /** Inlined CSS (`<style>`); sits with the stylesheet links, ahead of every head script. */
+  headStyles?: string
   headScripts?: string
   documentHeadTags?: string
   metadataUrl?: string
@@ -735,9 +759,10 @@ interface DocumentPage extends MetadataRenderPage {
   fontCss: string
   bodyIconLinks?: string
   bodyMetadata?: string
-  /** Request-time metadata arrives as a deferred stream chunk, not in the head. */
-  bodyMetadataDeferred?: boolean
+  /** Document metadata lives below the fold (streamed or deferred), so the head must not carry it. */
+  metadataInBody?: boolean
   compatBodyScript?: string
+  headStyles?: string
   headScripts?: string
   documentHeadTags?: string
   deferredScripts?: string
@@ -775,29 +800,53 @@ function titleTag(title: unknown): string {
   return value ? `<title>${escapeHtml(value)}</title>` : ''
 }
 
+// Head order, taken from React's Fizz preamble (Next inherits it verbatim): charset, preconnects,
+// the viewport meta, font/high-priority-image preloads, the precedence-ordered stylesheets, the bulk
+// preloads, then the bootstrap scripts. Everything registered AFTER that preamble flushes - late
+// preloads, and every ordinary <meta>/<title>/metadata <link>, which React hoists rather than writes
+// into the preamble - follows in encounter order.
+//
+// This only reorders the asset links; the head-vs-body split is untouched, so
+// metadataOnlyLinks still travel with the metadata and never appear when it streams into the body.
 function renderDocumentStart(page: DocumentPage) {
   const rendered = page.shell === 'layout' ? page.body : `<main data-pnext-root>${page.body}</main>`
-  const slotMode = pageSlotMarkerMode(page, rendered)
+  const slotMode = pageSlotMarkerMode(page)
   const body = unwrapUnusedPageSlot(rendered, slotMode)
   const viewport = viewportContent(page.viewport)
   const context = metadataContext(page)
   const headPage = page.bodyIconLinks
     ? { ...page, metadata: { ...page.metadata, icons: undefined }, suppressIconLinks: true }
     : page
+  const [connects, preloads, stylesheets, bulkPreloads, lateHints] = assetLinkGroups(headPage)
+  // Joined with the empty slots dropped: a head with no fonts/hints/inline CSS used to ship a blank
+  // line per unused slot, and the bucket split multiplies them.
+  const head = [
+    '<meta charSet="utf-8"/>',
+    connects,
+    `<meta name="viewport" content="${escapeHtml(viewport)}"/>`,
+    preloads,
+    page.fontCss ? `<style data-pnext-font>${page.fontCss}</style>` : '',
+    page.headStyles,
+    stylesheets,
+    bulkPreloads,
+    page.headScripts,
+    lateHints,
+    page.documentHeadTags,
+    page.viewport.colorScheme
+      ? `<meta name="color-scheme" content="${escapeHtml(page.viewport.colorScheme)}"/>`
+      : '',
+    themeColorTags(page.viewport.themeColor),
+    page.metadataInBody ? '' : titleTag(page.metadata.title),
+    page.metadataInBody ? '' : metadataTags(page.metadata, context),
+    page.metadataInBody ? '' : metadataOnlyLinks(headPage, context),
+    page.head,
+  ]
+    .filter(Boolean)
+    .join('\n    ')
   // Next emits the doctype and <html> on one line; tests match /^<!DOCTYPE html><html/.
   const html = `<!DOCTYPE html><html${documentAttrs(page.htmlProps, page.metadata.lang ? { lang: page.metadata.lang } : {})}>
   <head>
-    <meta charSet="utf-8"/>
-    <meta name="viewport" content="${escapeHtml(viewport)}"/>
-    ${page.viewport.colorScheme ? `<meta name="color-scheme" content="${escapeHtml(page.viewport.colorScheme)}"/>` : ''}
-    ${themeColorTags(page.viewport.themeColor)}
-    ${page.bodyMetadata || page.bodyMetadataDeferred ? '' : titleTag(page.metadata.title)}
-    ${page.bodyMetadata || page.bodyMetadataDeferred ? '' : metadataTags(page.metadata, context)}
-    ${page.bodyMetadata || page.bodyMetadataDeferred ? '' : headLinks(headPage, context)}
-    ${page.headScripts ?? ''}
-    ${page.documentHeadTags ?? ''}
-    ${page.fontCss ? `<style data-pnext-font>${page.fontCss}</style>` : ''}
-    ${page.head}
+    ${head}
   </head>
   <body${documentAttrs(page.bodyProps)}>
     ${body}
@@ -944,14 +993,11 @@ interface CollectedHeadScript {
 }
 
 function clearHeadScripts() {
-  ;(globalThis as { __PNEXT_HEAD_SCRIPTS__?: CollectedHeadScript[] }).__PNEXT_HEAD_SCRIPTS__ = []
+  clearRenderBuffer('head')
 }
 
 function takeHeadScripts() {
-  const holder = globalThis as { __PNEXT_HEAD_SCRIPTS__?: CollectedHeadScript[] }
-  const scripts = holder.__PNEXT_HEAD_SCRIPTS__ ?? []
-  holder.__PNEXT_HEAD_SCRIPTS__ = []
-  return scripts
+  return takeRenderBuffer<CollectedHeadScript>('head')
 }
 
 function renderCollectedHeadScripts() {
@@ -990,16 +1036,11 @@ interface CollectedDeferredScript {
 }
 
 function clearDeferredScripts() {
-  ;(
-    globalThis as { __PNEXT_DEFERRED_SCRIPTS__?: CollectedDeferredScript[] }
-  ).__PNEXT_DEFERRED_SCRIPTS__ = []
+  clearRenderBuffer('deferred')
 }
 
 function takeDeferredScripts(): CollectedDeferredScript[] {
-  const holder = globalThis as { __PNEXT_DEFERRED_SCRIPTS__?: CollectedDeferredScript[] }
-  const scripts = holder.__PNEXT_DEFERRED_SCRIPTS__ ?? []
-  holder.__PNEXT_DEFERRED_SCRIPTS__ = []
-  return scripts
+  return takeRenderBuffer<CollectedDeferredScript>('deferred')
 }
 
 // A `type="module"` script, deferred like the hydration entry and ordered after it, so any
@@ -1221,18 +1262,29 @@ function createPageProps(options: RenderRequestOptions): PageProps {
       }
     }
   }
+  const params = trackedParams(options)
+  const searchParams = trackedSearchParams(pageSearchParams(childrenSourceSearchParams(options)))
   return {
     // markRuntimeApiOnAwait is the identity outside a runtime-prefetch
     // prerender; inside one, awaiting params/searchParams arms the sync-IO
     // abort exactly as awaiting cookies()/headers() does.
-    params: markRuntimeApiOnAwait(settledPromise(trackedParams(options))),
+    params: markRuntimeApiOnAwait(legacySyncProps(settledPromise(params), 'params', params)),
     searchParams: markRuntimeApiOnAwait(
-      settledPromise(trackedSearchParams(pageSearchParams(childrenSourceSearchParams(options)))),
+      legacySyncProps(settledPromise(searchParams), 'searchParams', searchParams),
     ),
     request: options.request ? pageRequest(options.request) : undefined,
   }
 }
 
+/** Next 15's transitional sync surface on params/searchParams; identity unless compat enables it. */
+function legacySyncProps<T extends object>(
+  promise: Promise<T>,
+  kind: 'params' | 'searchParams',
+  value: T,
+): Promise<T> {
+  return getRenderExtensions().legacySyncProps(promise, kind, value)
+}
+
 /**
  * The render's concrete params, wrapped in the compat vary-params tracking view
  * when one is active (segment-prefetch renders). Outside a tracking scope the
@@ -1569,9 +1621,6 @@ export async function renderPageResponse(options: RenderOptions) {
               headers: {
                 'content-type': 'text/html; charset=utf-8',
                 ...(truncated ? { 'x-nextjs-postponed': '1' } : {}),
-                // Error pages must never outlive the failure that produced them
-                // in any cache (browser, prefetch, or intermediary).
-                ...((page.status ?? 200) >= 400 ? { 'cache-control': 'no-store' } : {}),
               },
             },
           )
@@ -2544,7 +2593,7 @@ export async function renderGlobalNotFoundResponse(
     )
     response = new Response(pageStream(page), {
       status: 404,
-      headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
+      headers: { 'content-type': 'text/html; charset=utf-8' },
     })
   }
   // Next always marks the not-found page noindex.
@@ -2587,7 +2636,7 @@ export async function renderNotFoundForRoute(
   )
   const response = new Response(pageStream(page), {
     status: 404,
-    headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
+    headers: { 'content-type': 'text/html; charset=utf-8' },
   })
   const html = await response.text()
   const withRobots = html.includes('name="robots"')
@@ -2926,7 +2975,6 @@ async function pageRender(options: RenderOptions, stream: boolean): Promise<Page
             layoutFiles,
             clientComponents,
             clientComponentsPreload,
-            resolveDynamicMetadataRoutes: options.resolveDynamicMetadataRoutes,
           },
           loadedPage,
           stream,
@@ -3172,9 +3220,9 @@ function withGlobalErrorReportScript(html: string, error: SerializedError): stri
 }
 
 function withGlobalErrorStylesheet(html: string, config: ResolvedConfig): string {
-  const asset = `${config.outPath}/public/assets/global-error.css`
+  const asset = `${config.outPath}/public/assets/${emittedAssetName(config, 'global-error.css')}`
   if (!existsSync(asset)) return html
-  const link = `<link rel="stylesheet" href="${withAssetPrefix(config, '/assets/global-error.css')}">`
+  const link = `<link rel="stylesheet" href="${assetHref(config, 'global-error.css')}">`
   if (html.includes('</head>')) return html.replace('</head>', `${link}</head>`)
   return html.replace(/<html(?:\s[^>]*)?>/i, tag => `${tag}<head>${link}</head>`)
 }
@@ -3287,7 +3335,16 @@ async function resolveSelectedSlotMetadata(
   return { entries: [], runtime: false }
 }
 
-async function renderTree(
+/**
+ * One render, one buffer frame: the resource hints, head scripts and deferred scripts this render
+ * collects are its own, so a render running alongside it (a build's next route, a not-found
+ * document, another request) can neither drain them nor add to them.
+ */
+function renderTree(...args: Parameters<typeof renderTreeInFrame>): Promise<PageRender> {
+  return renderBufferScope.run(newRenderBufferFrame(), () => renderTreeInFrame(...args))
+}
+
+async function renderTreeInFrame(
   options: RenderOptions,
   tree: ComponentChildren,
   stream: boolean,
@@ -3488,19 +3545,22 @@ async function renderTree(
   const prebuiltRouteMetadata = hasMetadataExtensions
     ? undefined
     : options.staticRouteMetadata?.[staticRouteMetadataKey(options.url.pathname)]
+  // No prebuilt entry means nobody has resolved app/manifest.ts & friends for this
+  // pathname yet: dev never prebuilds, and the build only prebuilds paths it knows
+  // (so every parameterised route arrives here). Resolving is the only way those
+  // documents carry the same metadata-file links as the paramless ones. An app with
+  // no dynamic metadata files short-circuits inside withDynamicMetadataRoutes.
   const staticMetadata =
     prebuiltRouteMetadata ??
-    (hasMetadataExtensions || options.resolveDynamicMetadataRoutes
-      ? await profileRenderStep(profile, 'dynamic metadata routes', () =>
-          withDynamicMetadataRoutes(
-            staticMetadataBase,
-            options.config.appPath,
-            options.route.file,
-            options.url.pathname,
-            file => importModule(file, options),
-          ),
-        )
-      : staticMetadataBase)
+    (await profileRenderStep(profile, 'dynamic metadata routes', () =>
+      withDynamicMetadataRoutes(
+        staticMetadataBase,
+        options.config.appPath,
+        options.route.file,
+        options.url.pathname,
+        file => importModule(file, options),
+      ),
+    ))
   const composeMetadata = (pageMeta: Metadata) => {
     const merged = supersededSlotPage
       ? mergeMetadataEntries(layoutRender.metadata, slotMetadata.entries)
@@ -3614,17 +3674,18 @@ async function renderTree(
     getDocumentScriptExtensions().stylesheetPrecedence(options.config),
   )
   const cssHrefStart = profileRenderMark(profile)
-  const globalStylesheet =
+  let globalStylesheet =
     // global-not-found replaces the document without the root layout, so the
     // root layout's global sheet must not load (its CSS ships in the route's
     // own chunk, built with includeGlobalCss).
     options.route.id === 'global-not-found' ? undefined : globalCssHref(options.config)
-  const routeStylesheet = routeCssHref(options.route, options.config)
+  let routeStylesheet = routeCssHref(options.route, options.config)
+  // File names, not logical ones: the inline path READS these off disk, so it has
+  // to spell them the way the build emitted them (content-hashed in production).
   const stylesheetAssets = [
     ...(globalStylesheet ? ['global.css'] : []),
-    ...(options.route.cssAssets ??
-      (options.route.cssImports.length ? [`${options.route.id}.css`] : [])),
-  ]
+    ...routeCssAssetNames(options.route),
+  ].map(name => emittedAssetName(options.config, name))
   profileRenderSince(profile, 'css hrefs', cssHrefStart)
   const inlineStylesheets = profileRenderSyncStep(profile, 'inline stylesheets', () =>
     getCssExtensions().inlineStylesheets(options.config, {
@@ -3634,6 +3695,18 @@ async function renderTree(
       ...(nonce ? { nonce } : {}),
     }),
   )
+  if (!inlineStylesheets && fonts.css) {
+    const fontAsset = await profileRenderStep(profile, 'font stylesheet', () =>
+      emitFontCssStylesheet(options.config, options.route.id, fonts.css, stylesheetAssets[0], {
+        dev: Boolean(options.dev),
+      }),
+    )
+    const fontHref = assetHref(options.config, fontAsset)
+    if (globalStylesheet) globalStylesheet = fontHref
+    else if (Array.isArray(routeStylesheet))
+      routeStylesheet = [fontHref, ...routeStylesheet.slice(1)]
+    else routeStylesheet = fontHref
+  }
   const stylesheetsStart = profileRenderMark(profile)
   const stylesheets = (
     inlineStylesheets
@@ -3672,9 +3745,11 @@ async function renderTree(
     nextCompatEnabled(options.config) && !options.dev
       ? `<script src="${escapeHtml(withAssetPrefix(options.config, '/_next/static/pnext/_buildManifest.js'))}"></script>`
       : ''
+  // Inlined CSS is a stylesheet, not a script: it belongs at the stylesheet slot so the cascade
+  // (and the emitted order) matches the linked path.
+  const headStyles = inlineStylesheets?.join('\n') ?? ''
   const headScripts = profileRenderSyncStep(profile, 'head scripts', () =>
     [
-      inlineStylesheets?.join('\n'),
       renderCollectedHeadScripts(),
       bootstrapScripts,
       compatBuildManifestScript,
@@ -3730,25 +3805,23 @@ async function renderTree(
     resourceHints,
     staticMetadata,
     fontPreloads: fonts.preloads,
+    headStyles,
     headScripts,
     deferredScripts,
     nonce,
     propsScript: extra.propsScript ?? '',
     routeScript,
     clientScript,
-    // Whether anything client-side ever mounts INTO the page slot: a whole-page `'use client'` route
-    // hydrates on `#pnext-page` itself, and islands are adopted through it. A route that ships the
-    // entry only for the router runtime mounts nothing there.
-    hasClientMounts: options.route.client || options.route.clientReferences.length > 0,
+    hasClientMounts: pageSlotIsMountTarget(options),
     devScript,
     streamChunks: streamState.deferred,
     lateChunks,
     status: extra.status,
     viewport,
-    fontCss: inlineStylesheets ? '' : fonts.css,
+    fontCss: '',
     ...(bodyIconLinks ? { bodyIconLinks } : {}),
     ...(bodyMetadata ? { bodyMetadata } : {}),
-    ...(pendingPageMetadata ? { bodyMetadataDeferred: true } : {}),
+    ...(bodyMetadata || pendingPageMetadata ? { metadataInBody: true } : {}),
     compatBodyScript: getDocumentScriptExtensions().documentBodyScripts(options.config),
     // The shell's server-inserted HTML was drained when the stream shell
     // finished (streamState.insertedHead); anything still registered is emitted
@@ -4246,7 +4319,10 @@ async function renderErrorPage(options: RenderOptions, error: unknown, stream: b
       nextCompatEnabled(options.config),
     )
     const reset = errorResetCallback()
-    return renderTree(
+    // Awaited inside the try on purpose: a bare `return` hands the rejection to
+    // the caller, and an error boundary that fails to render answered with a
+    // bodiless 500 instead of the generic error document.
+    return await renderTree(
       options,
       h(
         'div',
@@ -4377,6 +4453,22 @@ function resolveThrownError(error: unknown, compatNext: boolean): Error {
   return wrapped ?? new Error(String(error))
 }
 
+/**
+ * The logged trace, always carrying the error's identity. Bun drops the `Name: message` header when
+ * it source-maps a stack, so a bare frame list would log as `⨯ Error` with nothing to diagnose.
+ */
+export function errorLogTrace(error: Error): string {
+  const name = error.name || 'Error'
+  const header = error.message ? `${name}: ${error.message}` : name
+  const stack = error.stack
+  if (!stack) return header
+  if (stack.startsWith(header)) return stack
+  // Source-mapping keeps the name and drops `: <message>`, so a stack that opens with the bare name
+  // is a header to complete, not one to prepend - matching on the name alone would lose the message.
+  if (stack.startsWith(`${name}\n`)) return `${header}${stack.slice(name.length)}`
+  return `${header}\n${stack}`
+}
+
 function logDevError(options: RenderOptions, error: Error, clientSsrError = false) {
   const seen = isBuildError(error) ? loggedBuildErrors : loggedRuntimeErrors
   if (seen.has(error)) return
@@ -4386,7 +4478,7 @@ function logDevError(options: RenderOptions, error: Error, clientSsrError = fals
   // rejection guard and the start.ts top-level catch so whichever site fires
   // first wins (dedupe-rsc-error-log asserts one log per error).
   if (!markErrorLogged(error)) return
-  const trace = error.stack ?? error.message
+  const trace = errorLogTrace(error)
   if (clientSsrError) {
     // A client-page SSR error is replayed in the browser (no digest attached),
     // but Next's prod server log still prints it in the `⨯ <trace>` shape —
@@ -5153,6 +5245,7 @@ async function resolvePartialSuspense(
         renderSuspenseReplacement(
           String(id),
           parts.join(''),
+          state.options,
           documentNonce(state.options.request),
           dynamic,
         ),
@@ -5162,7 +5255,12 @@ async function resolvePartialSuspense(
     const resolved = await resolveServerTree(node.props.children, opaque)
     const html = await renderVNodeToString(h(Fragment, null, resolved), opaque)
     partial.chunks.push(
-      renderSuspenseReplacement(String(id), html, documentNonce(state.options.request)),
+      renderSuspenseReplacement(
+        String(id),
+        html,
+        state.options,
+        documentNonce(state.options.request),
+      ),
     )
     return null
   }
@@ -5477,6 +5575,7 @@ function deferSuspenseBoundary(
         renderSuspenseReplacement(
           id,
           await renderVNodeToString(h(Fragment, null, resolved), state),
+          state.options,
           nonce,
         ),
       )
@@ -5487,12 +5586,18 @@ function deferSuspenseBoundary(
         // the nearest not-found UI plus a noindex meta, or the redirect meta-refresh and
         // location.replace script. Both ride the chunk's own markup rather than the sent head.
         if (isNotFoundError(error)) {
-          return renderSuspenseReplacement(id, await renderStreamNotFoundBoundary(state), nonce)
+          return renderSuspenseReplacement(
+            id,
+            await renderStreamNotFoundBoundary(state),
+            state.options,
+            nonce,
+          )
         }
         if (isRedirectError(error)) {
           return renderSuspenseReplacement(
             id,
             metadataRedirectHtml(error.location, error.status),
+            state.options,
             nonce,
           )
         }
@@ -5513,6 +5618,7 @@ function deferSuspenseBoundary(
               needsClientEntry(state.options.route),
             ),
           ),
+          state.options,
           nonce,
         )
       }),
@@ -5840,6 +5946,17 @@ function elementVNode(
   return h(type as string, props, children)
 }
 
+/** The one message every core server-action refusal uses; see SERVER_ACTIONS_UNSUPPORTED. */
+function serverActionUnsupported(options: RenderOptions): Error {
+  return new Error(
+    serverActionsUnsupportedMessage({
+      file: options.route.serverActionFile ?? options.route.file,
+      route: options.route.route,
+      root: options.config.root,
+    }),
+  )
+}
+
 // Progressive enhancement for <form action={serverAction}>: render a real POST
 // form back to the current page URL with the id in a hidden field, so a no-JS
 // submit still dispatches (serveAction promotes the field to the next-action
@@ -5854,6 +5971,10 @@ function serverActionFormVNode(
   const rest = { ...props }
   delete rest.action
   if (!state) return h('form', rest, children)
+  // Core has no action registry and no dispatch endpoint, so there is nothing to
+  // wire this form to. Dropping the prop rendered a form that silently submits a
+  // GET to the current URL - undebuggable from the browser - so core refuses.
+  if (!nextCompatEnabled(state.options.config)) throw serverActionUnsupported(state.options)
   const enhanced = serverActionFormProps(props, state)
   if (!enhanced) return h('form', rest, children)
   return h('form', enhanced.props, enhanced.hidden, children)
@@ -5907,6 +6028,7 @@ function actionSubmitterVNode(
   state: ActionSerializeState,
 ) {
   const { formAction, ...rest } = props
+  if (!nextCompatEnabled(state.options.config)) throw serverActionUnsupported(state.options)
   const id = actionIdForFunction(formAction, state)
   if (!id) return h(type, rest, children)
   return h(
@@ -5922,6 +6044,25 @@ function actionSubmitterVNode(
   )
 }
 
+/**
+ * Convention props the framework itself supplies as FUNCTIONS (error.tsx's
+ * `reset`/`unstable_retry`) are documented API, so a `'use client'` boundary
+ * must be able to receive them. They ride the same `$$pnextErrorReset` marker
+ * compat writes; core reads it back in utils/serialize. Convention props are
+ * always top level, so this is one typeof per prop and no copy when there is
+ * nothing to rewrite.
+ */
+function serializeConventionProps(props: Record<string, unknown>): Record<string, unknown> {
+  let out: Record<string, unknown> | undefined
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof value !== 'function') continue
+    if (!(value as { [PROP_ERROR_RESET_MARKER]?: unknown })[PROP_ERROR_RESET_MARKER]) continue
+    out ??= { ...props }
+    out[key] = { [PROP_ERROR_RESET_MARKER]: true }
+  }
+  return out ?? props
+}
+
 /**
  * Replace function props (server actions handed to a client island) with the
  * serializable action-reference marker the client runtime revives. Non-action
@@ -5931,7 +6072,7 @@ function serializeActionProps(
   props: Record<string, unknown>,
   state: ActionSerializeState,
 ): Record<string, unknown> {
-  if (!nextCompatEnabled(state.options.config)) return props
+  if (!nextCompatEnabled(state.options.config)) return serializeConventionProps(props)
   // Taint check runs on the RAW props: serializeActionValue copies plain (and
   // null-prototype) objects, which would drop the identity `process.env` is
   // recognized by.
@@ -6417,7 +6558,13 @@ async function readRenderModuleMetadata(
   }
 }
 
-function renderSuspenseReplacement(id: string, html: string, nonce?: string, slots?: number[]) {
+function renderSuspenseReplacement(
+  id: string,
+  html: string,
+  options: RenderOptions,
+  nonce?: string,
+  slots?: number[],
+) {
   // Streamed Suspense content rides in a `<div hidden>` (React/Next's own
   // streaming markup shape) rather than a `<template>`: tests (and tools like
   // cheerio) assert streamed-but-unswapped content sits under a `[hidden]`
@@ -6427,7 +6574,11 @@ function renderSuspenseReplacement(id: string, html: string, nonce?: string, slo
   // boundary's dynamic slots (comment-delimited), and promotion merges them with
   // the static slots the shell's `<template data-pnext-static>` already holds.
   const slotsAttribute = slots ? ` data-pnext-slots="${escapeHtml(slots.join(','))}"` : ''
-  return `<div hidden data-pnext-stream="${escapeHtml(id)}"${slotsAttribute}>${html}</div><script${nonceAttribute}>${suspenseReplaceScript(id)}</script>`
+  // A page whose slot sits under a Suspense (loading.tsx, a streamed leaf) ships the slot HERE
+  // rather than in the shell, so the same mount-target rule the document body applies has to run
+  // on the tail: $RC grafts these bytes into the live DOM, and an inert wrapper would re-enter it.
+  const body = unwrapUnusedPageSlot(html, streamPageSlotMode(options))
+  return `<div hidden data-pnext-stream="${escapeHtml(id)}"${slotsAttribute}>${body}</div><script${nonceAttribute}>${suspenseReplaceScript(id)}</script>`
 }
 
 async function renderVNodeToString(vnode: VNode, state?: ActionSerializeState) {
@@ -6553,8 +6704,11 @@ async function renderSuspendingStreamShell(
       const refresh = tail.includes('<preact-island')
         ? clientSuspenseRefreshScript(documentNonce(state.options.request))
         : ''
-      return serializeNeutralClientIslands(
-        `${inserted}${anchorInlineSuspenseHoles(tail)}${refresh}`,
+      // Same mount-target rule as the out-of-order chunks: an inline-suspense tail carries the page
+      // slot whenever the page itself suspended, and the graft lands it in the live DOM.
+      return unwrapUnusedPageSlot(
+        serializeNeutralClientIslands(`${inserted}${anchorInlineSuspenseHoles(tail)}${refresh}`),
+        streamPageSlotMode(state.options),
       )
     }),
   )
@@ -6586,7 +6740,12 @@ function clientSuspenseRefreshScript(nonce: string | undefined) {
   // markers before this script - which streams in the deferred tail - can run, but the element
   // survives adoption as the island's static children. Falls back to the comment markers when the
   // element is absent.
-  return `<script${nonceAttribute}>$RC=function(i,d){var h=document.querySelector('pnext-hole[data-pnext-hole="'+i+'"]');if(h){while(h.firstChild)h.removeChild(h.firstChild);while(d.firstChild)h.appendChild(d.firstChild);d.remove();return}var s,e,w=document.createTreeWalker(document,128);while(w.nextNode()){var n=w.currentNode;if(n.data==='$s:'+i)s=n;else if(n.data==='/$s:'+i)e=n;if(s&&e)break}if(!s||!e)return;var p=e.previousSibling;while(p&&p!==s){var x=p;p=p.previousSibling;x.remove()}while(d.firstChild)s.after(d.firstChild),s=s.nextSibling;d.remove()};document.querySelectorAll('preact-island[data-target]').forEach(function(d){$RC(d.getAttribute('data-target'),d)})</script>`
+  //
+  // The grafted content arrives AFTER the document-wide island bootstrap ran, so its islands are
+  // still comment markers no scan can see: materialize and re-mount once the graft is done, the same
+  // pair PROMO_RUNTIME runs for the `<pnext-suspense>` path. Without it every client component inside
+  // a streamed Suspense boundary stays inert server HTML - no hydration, no effects, no data fetch.
+  return `<script${nonceAttribute}>$RC=function(i,d){var h=document.querySelector('pnext-hole[data-pnext-hole="'+i+'"]');if(h){while(h.firstChild)h.removeChild(h.firstChild);while(d.firstChild)h.appendChild(d.firstChild);d.remove();return}var s,e,w=document.createTreeWalker(document,128);while(w.nextNode()){var n=w.currentNode;if(n.data==='$s:'+i)s=n;else if(n.data==='/$s:'+i)e=n;if(s&&e)break}if(!s||!e)return;var p=e.previousSibling;while(p&&p!==s){var x=p;p=p.previousSibling;x.remove()}while(d.firstChild)s.after(d.firstChild),s=s.nextSibling;d.remove()};document.querySelectorAll('preact-island[data-target]').forEach(function(d){$RC(d.getAttribute('data-target'),d)});window.__PNEXT_MATERIALIZE_CLIENT_ISLANDS__&&window.__PNEXT_MATERIALIZE_CLIENT_ISLANDS__(document);window.__PNEXT_MOUNT_ISLANDS__&&window.__PNEXT_MOUNT_ISLANDS__()</script>`
 }
 
 /**
@@ -6601,11 +6760,16 @@ function islandMarkerBootstrapTag(mode: PageSlotMarkerMode): string {
 
 /**
  * Elements-as-final leaves `div#pnext-page` in the document, but nothing mounts on it unless the
- * slot itself hydrates - and an inert wrapper would break the flat body children a
- * router-runtime-only route renders. Unwrap it.
+ * slot itself hydrates - and an inert wrapper would break the flat body children Next emits.
+ * Elements wire format: unwrap it. Comment wire format: empty the marker's attribute payload, which
+ * every materializer already reads as "no element to build" - so the slot stays a pure anchor pair
+ * on first paint AND on every soft navigation that lands on this document.
  */
 function unwrapUnusedPageSlot(html: string, mode: PageSlotMarkerMode): string {
-  if (mode === 'materialize' || getRenderExtensions().islandCommentWireFormat()) return html
+  if (mode === 'materialize') return html
+  if (getRenderExtensions().islandCommentWireFormat()) {
+    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
 }
@@ -6671,22 +6835,42 @@ function pageSlotSpan(html: string) {
  * against the live DOM, so `div#pnext-page` may only be rebuilt when something actually mounts on
  * it:
  *
- *   - `materialize`: a whole-page client route hydrates on the slot, or islands are adopted through
- *     it.
- *   - `keep`: the route ships the entry for the ROUTER RUNTIME only. The wrapper is not rebuilt,
- *     but the comment anchors stay - the page-slot machinery locates the slot from the comment pair
- *     just as well as from the element.
+ *   - `materialize`: a whole-page client route hydrates on the slot, or a client ROOT layout
+ *     re-renders the page through it.
+ *   - `keep`: nothing mounts on the slot - the route ships the entry for islands and/or the router
+ *     runtime only. The wrapper is not rebuilt, but the comment anchors stay: the page-slot
+ *     machinery locates the slot from the comment pair just as well as from the element.
  *   - `drop`: no client runtime at all, so nothing will ever read the anchors.
  */
 type PageSlotMarkerMode = 'materialize' | 'keep' | 'drop'
 
-function pageSlotMarkerMode(page: DocumentPage, body: string): PageSlotMarkerMode {
+/**
+ * Whether anything client-side ever mounts INTO the page slot. Only two things do: a whole-page
+ * `'use client'` route (it hydrates on `#pnext-page` itself) and a `'use client'` ROOT layout (the
+ * entry's client shell re-renders the document through it and reads the slot as its children).
+ * ISLANDS DO NOT - each mounts on its own `pnext-client` host - so an island-only route keeps Next's
+ * wrapper-free body. Mirrors client/build.ts `hasClientRootLayout`, which decides whether the entry
+ * carries the shell path at all.
+ */
+function pageSlotIsMountTarget(options: RenderOptions): boolean {
+  if (options.route.client) return true
+  const rootLayout = (options.layoutFiles ??
+    findLayouts(options.config.appPath, options.route.file))[0]
+  return Boolean(rootLayout && options.route.clientReferences.some(ref => ref.file === rootLayout))
+}
+
+function pageSlotMarkerMode(page: DocumentPage): PageSlotMarkerMode {
   if (!page.clientScript) return 'drop'
-  // The route manifest's client flags are the authority (a client page carries
-  // no island marker of its own); the body scan additionally covers islands
-  // contributed by an ancestor layout outside this route's own references.
-  if (page.hasClientMounts || /<!--pnext-client|<pnext-client\b/.test(body)) return 'materialize'
-  return 'keep'
+  return page.hasClientMounts ? 'materialize' : 'keep'
+}
+
+/**
+ * The same mode for a streamed tail chunk, which is assembled before the document knows whether it
+ * ships a client script. `keep` and `drop` dissolve the slot identically here (only the bootstrap
+ * script distinguishes them), so the mount-target question is the whole decision.
+ */
+function streamPageSlotMode(options: RenderOptions): PageSlotMarkerMode {
+  return pageSlotIsMountTarget(options) ? 'materialize' : 'keep'
 }
 
 function clientIslandMarkerBootstrapSource(mode: PageSlotMarkerMode = 'materialize') {
@@ -6747,45 +6931,48 @@ function hStreamError(
   hasClientRuntime = false,
 ): VNode<any> {
   const resolvedError = resolveThrownError(error, compatNext)
-  if (!dev) {
-    // Compat: carry the serialized boundary error (redacted message + digest)
-    // on the marker so the client error runtime can replace this fallback with
-    // the route's error.js boundary (Next renders the nearest error boundary
-    // for a server error inside a streamed Suspense hole; its unstable_retry
-    // soft-refreshes and recovers). Core keeps the plain generic marker.
-    const serialized = compatNext
-      ? getRenderExtensions().serializeError({ error: resolvedError, dev })
-      : undefined
-    const marker = h(
-      'pnext-error',
-      {
-        'data-pnext-stream-error': true,
-        ...(serialized
-          ? {
-              'data-pnext-error-message': serialized.message,
-              ...(serialized.digest ? { 'data-pnext-error-digest': serialized.digest } : {}),
-            }
-          : {}),
-      },
-      (compatNext
+  // Compat: carry the serialized boundary error (redacted message + digest)
+  // on the marker so the client error runtime can replace this fallback with
+  // the route's error.js boundary (Next renders the nearest error boundary
+  // for a server error inside a streamed Suspense hole; its unstable_retry
+  // soft-refreshes and recovers). Core keeps the plain generic marker.
+  const serialized = compatNext
+    ? getRenderExtensions().serializeError({ error: resolvedError, dev })
+    : undefined
+  // The marker's own content is what stays on screen when nothing escalates it. Dev keeps the
+  // diagnostic card there - Next renders the error boundary in dev too, so the marker must be emitted
+  // either way; substituting the card for the marker stranded the route's error.js.
+  const fallback = dev
+    ? genericErrorTree(resolvedError, true, compatNext)
+    : ((compatNext
         ? getRenderExtensions().genericErrorTitle({ error: resolvedError, dev })
-        : undefined) ?? 'Application error',
-    )
-    // A page with no client components ships no error runtime, so nothing can escalate the marker
-    // client-side. Emit a self-contained fallback that swaps in the built-in global-error document
-    // unless the runtime announces itself (__PNEXT_STREAM_ERROR_RUNTIME__), in which case it owns
-    // the marker instead.
-    const fallbackScript =
-      compatNext && !hasClientRuntime ? streamErrorDocumentScript(serialized) : undefined
-    if (!fallbackScript) return marker
-    return h(
-      Fragment,
-      null,
-      marker,
-      h('script', { dangerouslySetInnerHTML: { __html: fallbackScript } }),
-    )
-  }
-  return genericErrorTree(resolvedError, true, compatNext)
+        : undefined) ?? 'Application error')
+  const marker = h(
+    'pnext-error',
+    {
+      'data-pnext-stream-error': true,
+      ...(serialized
+        ? {
+            'data-pnext-error-message': serialized.message,
+            ...(serialized.digest ? { 'data-pnext-error-digest': serialized.digest } : {}),
+          }
+        : {}),
+    },
+    fallback,
+  )
+  // A page with no client components ships no error runtime, so nothing can escalate the marker
+  // client-side. Emit a self-contained fallback that swaps in the built-in global-error document
+  // unless the runtime announces itself (__PNEXT_STREAM_ERROR_RUNTIME__), in which case it owns
+  // the marker instead. Dev needs none: its card is already the marker's visible content.
+  const fallbackScript =
+    !dev && compatNext && !hasClientRuntime ? streamErrorDocumentScript(serialized) : undefined
+  if (!fallbackScript) return marker
+  return h(
+    Fragment,
+    null,
+    marker,
+    h('script', { dangerouslySetInnerHTML: { __html: fallbackScript } }),
+  )
 }
 
 // Inline bootstrap flushed after a stream-error marker: replaces the document
@@ -6982,19 +7169,18 @@ async function applyLayouts(
     // postpone its boundary too (not read an empty object). Reuse the page-level
     // hanging params promise so the whole shell is param-independent.
     if (options.fallbackParams) return { ...layoutProps, params: hangingPromise('params') }
+    // The scoped params go through the vary-tracking extension under the LAYOUT
+    // segment kind: compat keys the layout's cache frame on the params this
+    // layout reads, independently of the page's own set. Outside a tracking
+    // scope the extension is the identity, so ordinary renders pay nothing (see
+    // compat/segment/vary-params.ts).
+    const scopedParams = getRenderExtensions().trackVaryParams(
+      layoutParamsForDir(options.config.appPath, dirname(layoutFile), options.params ?? {}),
+      { kind: 'params', segment: 'layout' },
+    )
     return {
       ...layoutProps,
-      // The scoped params go through the vary-tracking extension under the
-      // LAYOUT segment kind: compat keys the layout's cache frame on the params
-      // this layout reads, independently of the page's own set. Outside a
-      // tracking scope the extension is the identity, so ordinary renders pay
-      // nothing (see compat/segment/vary-params.ts).
-      params: Promise.resolve(
-        getRenderExtensions().trackVaryParams(
-          layoutParamsForDir(options.config.appPath, dirname(layoutFile), options.params ?? {}),
-          { kind: 'params', segment: 'layout' },
-        ),
-      ),
+      params: legacySyncProps(Promise.resolve(scopedParams), 'params', scopedParams),
     }
   }