@wular/pnext 0.0.24 → 0.1.0

package/src/client/router/runtime.ts

@@ -45,7 +45,7 @@ import type {
   SoftNavigateOptions,
 } from './types'
 import type { LinkClickTarget } from './hub'
-import { elementInPageSlot, graftPageSlot, loadingShellTarget } from './page-slot'
+import { elementInPageSlot, graftPageSlot, loadingShellTarget, pageSlotRange } from './page-slot'
 // ---------------------------------------------------------------------------
 // DOCUMENTS
 // ---------------------------------------------------------------------------
@@ -184,19 +184,6 @@ function currentNavState(): DocumentNavState {
   return state
 }
 
-/**
- * The static classification the server inlined into `#__PNEXT_NAV_STATE__`. Seeds
- * a hard load's prefetch entry with the route's true static reuse window.
- * Absent/parse-failure is treated as dynamic.
- */
-function documentStaticHint(): StaticHint | null {
-  const script =
-    typeof document.getElementById === 'function'
-      ? document.getElementById('__PNEXT_NAV_STATE__')
-      : null
-  return staticHintFromJson(script?.textContent ?? null)
-}
-
 export interface StaticHint {
   isStatic: boolean
   staleTime?: number
@@ -215,15 +202,6 @@ function documentStaticHintFromHtml(html: string): StaticHint | null {
   return staticHintFromJson(navStateJson(html))
 }
 
-/**
- * True when the live document came from a `prefetch = 'allow-runtime'` route: it
- * has no shared static shell, so its cacheable stage is per-URL and only a
- * runtime prefetch can produce it.
- */
-function documentRuntimePrefetch(): boolean {
-  return window.__PNEXT_ROUTE__?.runtimePrefetch === true
-}
-
 /** The same flag read out of a document's SOURCE (a navigation response). */
 function htmlRuntimePrefetch(html: string): boolean {
   return routeStateFromHtml(html)?.runtimePrefetch === true
@@ -258,14 +236,15 @@ function staticHintFromJson(json: string | null): StaticHint | null {
 }
 
 function rootLayoutId(doc: Document): string | null {
-  return doc.documentElement?.getAttribute('data-pnext-root-layout') ?? null
+  return doc.documentElement?.getAttribute('data-pnext-root-layout')?.replace(/[?#].*/, '') ?? null
 }
 
 function rootLayoutChanged(incoming: Document) {
   const current = rootLayoutId(document)
   const next = rootLayoutId(incoming)
-  if (current === null || next === null) return false
-  return current !== next
+  // Import versions and cache-busting revisions describe the build that produced a document, not
+  // a different root layout. The renderer's canonical id never needs either suffix in production.
+  return current !== null && next !== null && current !== next
 }
 
 function isPNextDocument(doc: Document) {
@@ -469,26 +448,69 @@ function preloadModule(href: string) {
   document.head.append(link)
 }
 
-// Add the new document's stylesheets before the body swap and resolve once
-// they load, so the swap never paints unstyled. Resolves on error too — a
-// missing stylesheet should degrade styling, not wedge navigation.
-function addStylesheets(doc: Document) {
+// Sheets this runtime appended that have not settled yet, keyed on absolute href. A paint
+// that installs them and a later commit that awaits them are different calls, so the
+// promise has to outlive the one that created the link.
+const stylesheetLoads = new Map<string, [Promise<void>, () => void]>()
+
+// Append the document's stylesheets SYNCHRONOUSLY and hand back the loads still in flight.
+// Every path that puts the destination's content on screen goes through here: a paint that
+// commits a navigation without its route's sheets shows unstyled content until the dynamic
+// stage lands. Resolves on error too — a missing stylesheet should degrade styling, not
+// wedge navigation.
+function installStylesheets(doc: Document): Promise<void>[] {
   const pending: Promise<void>[] = []
   for (const link of doc.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"][href]')) {
     const href = link.getAttribute('href')
-    if (!href || findStylesheet(href)) continue
-    pending.push(
-      new Promise(resolve => {
-        const sheet = document.createElement('link')
-        sheet.rel = 'stylesheet'
-        sheet.href = href
-        sheet.onload = () => resolve()
-        sheet.onerror = () => resolve()
-        document.head.append(sheet)
-      }),
-    )
+    if (!href) continue
+    const key = absoluteStylesheetHref(href)
+    const installed = findStylesheet(href)
+    if (installed) {
+      // Already in the document — possibly installed by an earlier paint this
+      // navigation, whose load the commit must still wait out.
+      const inFlight = stylesheetLoads.get(key!)
+      if (inFlight) {
+        // A memory-cached/restored sheet can become usable without replaying `load`.
+        // Its DOM-visible readiness is authoritative; release the earlier paint's waiter.
+        // findStylesheet can return an SSR/body-streamed or island-owned same-href link,
+        // so only settle the waiter recorded for the link this runtime created.
+        if (installed.sheet) inFlight[1]()
+        else pending.push(inFlight[0])
+      }
+      continue
+    }
+    const sheet = document.createElement('link')
+    sheet.rel = 'stylesheet'
+    sheet.href = href
+    let settle!: () => void
+    const load = new Promise<void>(resolve => {
+      settle = () => {
+        // The sheet can be pruned while its request is still in flight and then
+        // reinstalled by a back navigation. Do not let the abandoned request
+        // erase the newer request's promise from the dedup map.
+        if (stylesheetLoads.get(key!)?.[0] === load) {
+          stylesheetLoads.delete(key!)
+        }
+        resolve()
+      }
+    })
+    sheet.onload = settle
+    sheet.onerror = settle
+    if (key) {
+      stylesheetLoads.set(key, [load, settle])
+    }
+    document.head.append(sheet)
+    pending.push(load)
+  }
+  return pending
+}
+
+function absoluteStylesheetHref(href: string) {
+  try {
+    return new URL(href, location.href).href
+  } catch {
+    return
   }
-  return Promise.all(pending)
 }
 
 // Route stylesheets the new document does not use accumulate across navigations;
@@ -522,7 +544,7 @@ function pnextStylesheet(href: string) {
 
 function findStylesheet(href: string) {
   const target = new URL(href, location.href).href
-  return [...document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"][href]')].some(
+  return [...document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"][href]')].find(
     link => link.href === target,
   )
 }
@@ -555,7 +577,9 @@ function materializeClientIslandMarkers(root: Document) {
   const hasClientRuntime = Boolean(entryScriptSrc(root))
   while (walker.nextNode()) comments.push(walker.currentNode as Comment)
   for (const start of comments.reverse()) {
-    const match = /^(pnext-client(?:-after)?|pnext-page):([^>]*)$/.exec(start.data)
+    const match = /^(pnext-client(?:-after)?|pnext-static-children|pnext-page):([^>]*)$/.exec(
+      start.data,
+    )
     const kind = match?.[1]
     const encoded = match?.[2]
     if (!kind || !encoded || !start.parentNode) continue
@@ -569,7 +593,8 @@ function materializeClientIslandMarkers(root: Document) {
       continue
     }
     const container = document.createElement('div')
-    const tag = kind === 'pnext-page' ? 'div' : 'pnext-client'
+    const tag =
+      kind === 'pnext-page' ? 'div' : kind === 'pnext-client-after' ? 'pnext-client' : kind
     container.innerHTML = `<${tag} ${encoded}></${tag}>`
     const island = container.firstElementChild
     if (!island) continue
@@ -908,6 +933,95 @@ function matchPreservedClientPage(
   return { root, nodes }
 }
 
+// When a client layout adopts the page slot, its marker range disappears from the LIVE DOM and the
+// page's client components become ordinary children inside a preserved provider island. Give those
+// components a route-entry key on the incoming adoption source: Preact then unmounts only the page
+// subtree while PageTransition, providers, and layout ancestors stay mounted.
+// `key` is consumed by createElement and is not exposed as an application prop.
+function keySlotlessClientPage(doc: Document, key: string) {
+  const slot = pageSlotRange(doc.body)
+  if (!slot) return
+  const roots: Element[] = []
+  for (const node of slot[2]) {
+    if (!(node instanceof Element)) continue
+    if (node.matches('pnext-client[data-pnext-client]')) roots.push(node)
+    roots.push(...node.querySelectorAll('pnext-client[data-pnext-client]'))
+  }
+  for (const [index, root] of roots.entries()) {
+    try {
+      const props = JSON.parse(root.getAttribute('data-pnext-props') ?? '{}') as Record<
+        string,
+        unknown
+      >
+      props.key = `pnext-page:${key}:${index}`
+      root.setAttribute('data-pnext-props', JSON.stringify(props))
+    } catch {
+      // Invalid island props will be diagnosed by the entry mount; navigation must still commit.
+    }
+  }
+}
+
+function hasSlotlessClientRootLayout(doc: Document, preserved: LiveIslandRoot[]) {
+  if (pageSlotRange(document.body) !== null || preserved.length === 0) return false
+  return preserved.some((root, index) => {
+    // After adoption, a client root layout is itself a direct body child. Its incoming clone may
+    // expose the page marker through serialized children, but older/generated entries can keep the
+    // route-screen roots beside it instead, so the direct-body topology is the durable signal.
+    if (root.parentElement === document.body) return true
+    const placeholder = doc.querySelector<LiveIslandRoot>(`[${PRESERVE_ATTRIBUTE}="${index}"]`)
+    return placeholder !== null && pageSlotRange(placeholder) !== null
+  })
+}
+
+async function flushClientEffects() {
+  if (window.requestAnimationFrame) {
+    await new Promise<void>(resolve => window.requestAnimationFrame(() => resolve()))
+  } else {
+    await Promise.resolve()
+  }
+}
+
+// A slotless live tree cannot be partially unmounted through a DOM container: the page lives as
+// adopted children of a preserved provider root. Re-render that root once with the incoming page
+// marker emptied while it is still in the old body. The temporary departure URL keeps pathname-keyed
+// layout effects stable; after Preact flushes the outgoing page's cleanup, the real target render can
+// mount its page fresh against the already-fired popstate flag.
+async function unmountSlotlessClientPage(
+  doc: Document,
+  preserved: LiveIslandRoot[],
+  entry: EntryModule | null | undefined,
+  departingRouteKey: string,
+): Promise<boolean> {
+  if (!entry?.mountRoute || preserved.length === 0) return false
+  let staged = false
+  for (let index = 0; index < preserved.length; index++) {
+    const placeholder = doc.querySelector<LiveIslandRoot>(`[${PRESERVE_ATTRIBUTE}="${index}"]`)
+    if (!placeholder) continue
+    const source = placeholder.cloneNode(true) as LiveIslandRoot
+    const slot = pageSlotRange(source)
+    if (!slot) continue
+    for (const node of slot[2]) node.remove()
+    if (slot[0] instanceof Element) slot[0].replaceChildren()
+    else slot[0].remove()
+    slot[1]?.remove()
+    preserved[index]!.__pnextIncoming = source
+    staged = true
+  }
+  if (!staged) return false
+
+  const targetState: unknown = history.state
+  const targetHref = location.href
+  const departureHref = new URL(departingRouteKey, location.origin).href
+  withSilentLocationChange(() => history.replaceState(targetState, '', departureHref))
+  try {
+    await entry.mountRoute()
+    await flushClientEffects()
+  } finally {
+    withSilentLocationChange(() => history.replaceState(targetState, '', targetHref))
+  }
+  return true
+}
+
 // A query-only nav that stays on the SAME route renders the same whole-page `'use client'`
 // root, so its live DOM must be preserved exactly like a refresh - otherwise the page
 // REMOUNTS and a queued action's `setState` closure updates an orphaned component. The
@@ -925,6 +1039,7 @@ function swapBody(
   preservedPage: PreservedClientPage | null = null,
   reusable = reusableBodyChildren(),
 ) {
+  const paintHold = document.querySelector<HTMLElement>('[data-pnext-navigation-paint-hold]')
   const fragment = document.createDocumentFragment()
   // The incoming document's entry src, remembered on <html> below so a snapshot
   // of the swapped (script-less) live DOM can still name its entry.
@@ -950,7 +1065,10 @@ function swapBody(
     const live = takeReusableBodyChild(reusable, node)
     fragment.append(live ?? document.importNode(node, true))
   }
-  if (preserved.length > 0) graftPreservedIslands(fragment, preserved)
+  const connected =
+    preserved.length > 0
+      ? graftPreservedIslands(fragment, preserved)
+      : new Map<Node, LiveIslandRoot>()
   if (segments.length > 0) graftPreservedServerSegments(fragment, segments)
   if (preservedPage) {
     const placeholder = fragment.querySelector(`[${PAGE_PRESERVE_ATTRIBUTE}]`)
@@ -958,19 +1076,135 @@ function swapBody(
     // preact tree (and its state) carries straight into the new body.
     if (placeholder) placeholder.replaceWith(...preservedPage.nodes)
   }
-  document.body.replaceChildren(fragment)
+  if (connected.size === 0) {
+    document.body.replaceChildren(fragment)
+  } else {
+    // Reconcile around direct-body layout roots without ever disconnecting them.
+    let cursor = document.body.firstChild
+    for (const desired of [...fragment.childNodes]) {
+      const node = connected.get(desired) ?? desired
+      if (node === cursor) cursor = cursor.nextSibling
+      else document.body.insertBefore(node, cursor)
+    }
+    while (cursor) {
+      const next = cursor.nextSibling
+      cursor.remove()
+      cursor = next
+    }
+  }
+  if (paintHold) document.body.append(paintHold)
   // Track the entry of what is now on screen (dropped when the incoming route
   // has none, so a stale entry is never attributed to it).
   if (entrySrc) document.documentElement.setAttribute(ENTRY_SCRIPT_ATTRIBUTE, entrySrc)
   else document.documentElement.removeAttribute(ENTRY_SCRIPT_ATTRIBUTE)
 }
 
+/** Keep the last complete screen painted while client roots mount into the committed document. */
+type NavigationPaintHold = HTMLElement & {
+  __pnextObserver?: MutationObserver
+}
+
+function removeNavigationPaintHold(hold: NavigationPaintHold) {
+  hold.__pnextObserver?.disconnect()
+  hold.remove()
+}
+
+function createNavigationPaintHold(): NavigationPaintHold | null {
+  // A newer navigation may start before the prior hold's settling frame. Retire
+  // that transaction synchronously so holds never nest (the older async release
+  // becomes a no-op).
+  const priorHold = document.querySelector<NavigationPaintHold>(
+    '[data-pnext-navigation-paint-hold]',
+  )
+  if (priorHold) removeNavigationPaintHold(priorHold)
+  const roots = [...document.body.children].filter(
+    element =>
+      !element.hasAttribute('data-pnext-navigation-paint-hold') &&
+      !/^(SCRIPT|STYLE|LINK|TEMPLATE)$/.test(element.tagName) &&
+      element.textContent?.trim(),
+  )
+  if (roots.length === 0) return null
+  const hold = document.createElement('div')
+  hold.setAttribute('data-pnext-navigation-paint-hold', '')
+  hold.setAttribute('aria-hidden', 'true')
+  hold.style.cssText =
+    'position:fixed;inset:0;z-index:2147483646;overflow:hidden;pointer-events:none;background:Canvas;visibility:visible!important'
+  hold.append(...roots.map(root => root.cloneNode(true)))
+  // The copy is paint-only: route mount scans and id lookups must never treat it as live UI.
+  for (const node of hold.querySelectorAll('[data-pnext-client]'))
+    node.removeAttribute('data-pnext-client')
+  for (const node of hold.querySelectorAll('[id]')) node.removeAttribute('id')
+  // Cloned media are NEW elements: an `autoplay` attribute replays them on insertion, and
+  // cloneNode copies attributes but not the live `muted` property - a video muted only via
+  // property starts AUDIBLE in the copy. Freeze every clone on its current frame instead.
+  for (const media of hold.querySelectorAll<HTMLMediaElement>('video,audio')) {
+    media.removeAttribute('autoplay')
+    media.muted = true
+    media.setAttribute('muted', '')
+    media.preload = 'none'
+    media.removeAttribute('src')
+    for (const source of media.querySelectorAll('source')) source.remove()
+  }
+  // A cloned iframe re-loads (and can re-play) its document; the paint copy needs only the box.
+  for (const frame of hold.querySelectorAll('iframe')) frame.removeAttribute('src')
+  return hold
+}
+
+function attachNavigationPaintHold(
+  hold: NavigationPaintHold | null,
+  scrollTop: number,
+  sequence: number,
+) {
+  if (!hold || sequence !== navigationSequence) return
+  // The opaque fixed clone covers the viewport while the committed tree mounts.
+  // Keep that live tree visible to focus management and selector observers;
+  // hiding <body> also hides every real destination element from browser gates.
+  document.body.append(hold)
+  hold.__pnextObserver ??= new MutationObserver(() => {
+    if (sequence !== navigationSequence) {
+      return removeNavigationPaintHold(hold)
+    }
+    if (!hold.isConnected) document.body.append(hold)
+  })
+  hold.__pnextObserver.observe(document.documentElement, { childList: true, subtree: true })
+  const scrollRoot = hold.querySelector<HTMLElement>('[data-scroll-root]')
+  if (scrollRoot) scrollRoot.scrollTop = scrollTop
+}
+
+async function releaseNavigationPaintHold(hold: NavigationPaintHold | null) {
+  if (!hold) return
+  // mountRoute, client effects and the navigation commit have completed before
+  // this runs. Keep the departing frame through the next rendering opportunity,
+  // then reveal the committed tree; content length is not a readiness signal.
+  if (window.requestAnimationFrame) {
+    await new Promise<void>(resolve => window.requestAnimationFrame(() => resolve()))
+  }
+  removeNavigationPaintHold(hold)
+}
+
 /**
  * Give focus back to the element that had it before the body swap: reattaching a
  * node blurs it, so a retained layout element would silently drop focus to <body>.
  * Focus the new tree already claimed (autofocus, segment focus) stands.
  */
-function restoreSwapFocus(focused: Element | null): void {
+function restoreSwapFocus(
+  focused: Element | null,
+  navigationTarget: HTMLElement | null = null,
+): void {
+  // Next applies scroll/focus after the changed segment has committed. pnext
+  // resolves that segment before a client root can dissolve its page markers,
+  // so remember the element the scroll action focused and reaffirm it after
+  // client reconciliation. This is intentionally ahead of restoring retained
+  // layout focus: an interactive/scrollable destination segment wins over the
+  // link that initiated the navigation.
+  if (navigationTarget?.isConnected) {
+    try {
+      navigationTarget.focus({ preventScroll: true })
+    } catch {
+      // Focus is best-effort; continue with retained-layout focus below.
+    }
+    if (document.activeElement === navigationTarget) return
+  }
   if (!(focused instanceof HTMLElement) || focused === document.body) return
   if (!focused.isConnected) return
   if (document.activeElement !== null && document.activeElement !== document.body) return
@@ -1249,6 +1483,7 @@ function disposeCachedRoot(root: LiveIslandRoot) {
 // fresh island props move onto the live element, and the detached placeholder (fresh
 // SSR children) is stashed for the entry's mountRoute to re-render in place.
 function graftPreservedIslands(fragment: DocumentFragment, preserved: LiveIslandRoot[]) {
+  const connected = new Map<Node, LiveIslandRoot>()
   for (const placeholder of [...fragment.querySelectorAll(`[${PRESERVE_ATTRIBUTE}]`)]) {
     const live = preserved[Number(placeholder.getAttribute(PRESERVE_ATTRIBUTE))]
     placeholder.removeAttribute(PRESERVE_ATTRIBUTE)
@@ -1260,8 +1495,15 @@ function graftPreservedIslands(fragment: DocumentFragment, preserved: LiveIsland
       live.setAttribute(attribute.name, attribute.value)
     }
     live.__pnextIncoming = placeholder
-    placeholder.replaceWith(live)
+    if (live.parentNode === document.body && placeholder.parentNode === fragment) {
+      const marker = document.createComment('pnext-preserved-root')
+      placeholder.replaceWith(marker)
+      connected.set(marker, live)
+    } else {
+      placeholder.replaceWith(live)
+    }
   }
+  return connected
 }
 
 function isDevDocument() {
@@ -1278,17 +1520,19 @@ function hardNavigate(href: string, replace?: boolean) {
 
 function saveScrollPosition() {
   try {
-    const snapshot = {
-      html: `<!doctype html>${document.documentElement.outerHTML}`,
-      finalUrl: location.href,
-      ok: true,
-    }
-    cacheEntryDocument(snapshot)
-    // Preserve the original commit time so the entry expires on the document's real
-    // age, not the departure moment.
-    storeBfDoc(location.pathname + location.search, snapshot, { preserveTime: true })
+    // The bfcache document is recorded when the route commits (and when a hard load settles).
+    // Do not overwrite it from entryDocCache here: a streamed hard load intentionally keeps its
+    // immutable pre-runtime source for history restoration, which can be only the loading shell.
+    // Refiling that source on departure would downgrade the complete settled bfcache document and
+    // make a full-prefetch Link back to the route commit a permanently suspended shell.
+    // The scrollable height rides along so a pop restore into a still-short swapped body can
+    // reserve it — the browser clamps scrollTo against the live height, silently losing the
+    // position when the restored content mounts a beat after the swap.
     history.replaceState(
-      { ...historyState(), __pnextScroll: [window.scrollX, window.scrollY] },
+      {
+        ...historyState(),
+        __pnextScroll: [window.scrollX, window.scrollY, document.documentElement.scrollHeight],
+      },
       '',
       location.href,
     )
@@ -2005,6 +2249,14 @@ export function evictClientRouterCache(options: { rearmVisiblePrefetches?: boole
   entryDocCache.clear()
   bfDocCache.clear()
   urlStaticFreshUntil.clear()
+  // Element sets outlive an evicted cache otherwise: in a multi-document host (tests, jsdom
+  // embedders) the previous document's links stay registered and get re-pinged against the next
+  // document's tree, spending prefetches nothing asked for.
+  visiblePrefetchElements.clear()
+  // Pending loads belong to the document that created their <link> elements. In a
+  // multi-document host (tests, jsdom embedders) a never-settling promise keyed by an
+  // absolute href would otherwise stall the next document's first commit on the same URL.
+  stylesheetLoads.clear()
   for (const entry of invalidated) notifyPrefetchInvalidation(entry, true)
   if (options.rearmVisiblePrefetches !== false) rearmVisiblePrefetches()
 }
@@ -2172,6 +2424,17 @@ function segmentSchedulerEnabled(): boolean {
   )
 }
 
+// Next always restores a history entry's bfcacheId, but retaining the inactive
+// React tree in an <Activity> boundary is exclusive to cacheComponents. Compat
+// stamps this exact value into the document; an unstamped core app must keep its
+// ordinary unmount/remount lifecycle.
+function activityBfcacheEnabled(): boolean {
+  return (
+    (process.browser || typeof window !== 'undefined') &&
+    (window as { __PNEXT_SEGMENT_SCHEDULER__?: boolean }).__PNEXT_SEGMENT_SCHEDULER__ === true
+  )
+}
+
 function acquirePrefetchSlot(task: PrefetchFetchTask, phase: number): Promise<boolean> {
   task.phase = phase
   if (task.cancelled) return Promise.resolve(false)
@@ -2276,6 +2539,11 @@ export interface PrefetchEntry {
 
 const prefetchCache = new Map<string, PrefetchEntry>()
 const prefetchedElements = new Set<Element>()
+// Next re-evaluates every currently visible Link when the committed URL/base tree changes:
+// the same href may need a different segment delta from the new route. Keep this separate from
+// `prefetchedElements` (which also includes intent-only and formerly visible elements used by
+// revalidation) so an ordinary navigation only pings links that are actually on screen.
+const visiblePrefetchElements = new Set<Element>()
 
 function touchCacheEntry<T>(cache: Map<string, T>, key: string, entry: T): void {
   // Map insertion order is our LRU order. Reads must move an entry to the end
@@ -2598,12 +2866,13 @@ export function prefetchRoute(
   const key = url.pathname + url.search
   const full = Boolean(options.full)
   const cacheKey = prefetchCacheKey(key, full)
+  // Track the element before the current-route short circuit. A visible link to the page we are
+  // already on has an empty prefetch delta now, but its delta changes after navigating away and
+  // it must be reconsidered against that new base tree.
+  if (options.element) prefetchedElements.add(options.element)
   // Prefetching the page we are already on is a no-op (Next's router produces
   // an empty delta for the current tree) — and it must not spend a request.
-  if (
-    (key === location.pathname + location.search || key === routerState.activeRouteKey) &&
-    !options.currentUrl
-  ) {
+  if ((key === locationKey() || key === routerState.activeRouteKey) && !options.currentUrl) {
     return Promise.resolve(null)
   }
   // A default prefetch carries only static segment data; search params are dynamic data
@@ -2612,7 +2881,6 @@ export function prefetchRoute(
   if (!options.full && url.pathname === location.pathname && !options.currentUrl) {
     return Promise.resolve(null)
   }
-  if (options.element) prefetchedElements.add(options.element)
   if (revalidationPrefetchBlocked) return Promise.resolve(null)
   // Hover intent on a link whose prefetch is already scheduled/pending: boost
   // it to the reserved Intent lane instead of spawning anything new.
@@ -2888,13 +3156,13 @@ function rscHash(input: string): string {
   return (hash >>> 0).toString(36)
 }
 
-// Read a streamed HTML response, delivering the shell to `onShell` the moment the server
-// flushes it, then returning the full buffered document. The shell carries every Suspense
-// fallback as a closed `<pnext-suspense>`, so the first read containing `</pnext-suspense>`
-// is the shell; it is sliced at the first `<template data-pnext-stream>` already in the
-// same read. A route with no Suspense boundary never fires onShell. The in-place
-// suspending path closes its fallback with preact's `<!--/$s:ID-->` comment instead and
-// streams content as `<preact-island data-target>`.
+// Read a streamed HTML response, offering the shell at the response-chunk boundary where the
+// navigation can commit it. A pending Suspense hole paints its fallback at that commit, exactly
+// like a browser receiving a streamed document shell; if the shell and its replacement arrive in
+// the same read, the complete content wins without an intermediate paint. The shell carries every
+// Suspense fallback as a closed `<pnext-suspense>`; replacement IDs distinguish resolved holes.
+// A route with no Suspense boundary never fires onShell. The in-place suspending path closes its
+// fallback with preact's `<!--/$s:ID-->` comment and streams content as `<preact-island data-target>`.
 const STREAM_CHUNK_MARKER = '<div hidden data-pnext-stream'
 const INLINE_CHUNK_MARKER = '<div hidden><preact-island'
 const SUSPENSE_FALLBACK_CLOSE = '</pnext-suspense>'
@@ -2903,13 +3171,43 @@ const SUSPENSE_FALLBACK_CLOSE = '</pnext-suspense>'
 const INLINE_FALLBACK_CLOSE = '</pnext-hole>'
 
 function streamChunkCut(buffer: string) {
-  const cuts = [buffer.indexOf(STREAM_CHUNK_MARKER), buffer.indexOf(INLINE_CHUNK_MARKER)].filter(
-    index => index !== -1,
+  const streamed = buffer.indexOf(STREAM_CHUNK_MARKER)
+  const inline = buffer.indexOf(INLINE_CHUNK_MARKER)
+  return streamed < 0 ? inline : inline < 0 ? streamed : Math.min(streamed, inline)
+}
+
+// A network read can end halfway through its final continuation. DOMParser auto-closes that
+// carrier, which would make materializeStreamedSegments graft partial markup over the fallback.
+// Stream carriers are top-level divs, so balance their nested div tags and retain every complete
+// same-read carrier while hiding the incomplete trailing one from shell logic.
+function completeStreamedPrefix(buffer: string): string {
+  const start = Math.max(
+    buffer.lastIndexOf(STREAM_CHUNK_MARKER),
+    buffer.lastIndexOf(INLINE_CHUNK_MARKER),
   )
-  return cuts.length > 0 ? Math.min(...cuts) : -1
+  if (start < 0) return buffer
+  const tail = buffer.slice(start)
+  return (tail.match(/<div\b/g)?.length ?? 0) === (tail.match(/<\/div>/g)?.length ?? 0)
+    ? buffer
+    : buffer.slice(0, start)
+}
+
+function streamHasPendingHole(buffer: string) {
+  for (const match of buffer.matchAll(/data-pnext-(?:suspense|hole)="([^"]+)"/g)) {
+    const suffix = `="${match[1]}"`
+    if (
+      !buffer.includes(`data-pnext-stream${suffix}`) &&
+      // Scope data-target to pnext's exact inline continuation wire form; app markup commonly
+      // uses the bare attribute for toggles and tabs.
+      !buffer.includes(`<preact-island hidden data-target${suffix}`)
+    ) {
+      return true
+    }
+  }
+  return false
 }
 
-async function readStreamedBody(
+export async function readStreamedBody(
   response: Response,
   onShell: (shellHtml: string) => void,
 ): Promise<string> {
@@ -2921,20 +3219,23 @@ async function readStreamedBody(
   for (;;) {
     const { done, value } = await reader.read()
     if (value) buffer += decoder.decode(value, { stream: true })
+    const shellBuffer = completeStreamedPrefix(buffer)
     if (
       !shellDelivered &&
-      (buffer.includes(SUSPENSE_FALLBACK_CLOSE) || buffer.includes(INLINE_FALLBACK_CLOSE)) &&
+      (shellBuffer.includes(SUSPENSE_FALLBACK_CLOSE) ||
+        shellBuffer.includes(INLINE_FALLBACK_CLOSE)) &&
       // A read that already ends the document has nothing left to stream: painting the
       // pre-chunk loading shell would commit a fallback stage the immediate full-document
       // swap replaces, and that replacement rides island mounts. Skip the shell and let
       // the caller swap the complete, materialized document.
-      !/<\/html>\s*$/.test(buffer)
+      !/<\/html>\s*$/.test(shellBuffer)
     ) {
-      shellDelivered = true
-      const cut = streamChunkCut(buffer)
-      const shell = cut === -1 ? buffer : buffer.slice(0, cut)
-      // Close the sliced shell so DOMParser sees a well-formed document.
-      onShell(`${shell}</body></html>`)
+      if (streamHasPendingHole(shellBuffer)) {
+        shellDelivered = true
+        // Expose only holes still pending at this commit. Continuations already present in the
+        // read are included so showLoadingShell can materialize them before choosing a fallback.
+        onShell(`${shellBuffer}</body></html>`)
+      }
     }
     // A late metadata tail (LATE_METADATA_HEADER) rides after the document bytes, so the
     // navigation must not wait for it: everything before the marker IS the document and
@@ -3011,6 +3312,8 @@ async function fetchPage(
   href: string,
   options: {
     navState?: DocumentNavState
+    /** Rendered URL this navigation departed from (popstate location already names the target). */
+    fromUrl?: string
     /**
      * 'auto' - a default prefetch (sends `next-router-prefetch`). 'full' - a
      * `prefetch={true}` full-page prefetch, which Next issues WITHOUT that header.
@@ -3048,7 +3351,7 @@ async function fetchPage(
     'next-router-state-tree': encodeURIComponent(JSON.stringify(state)),
     // The current URL identifies the already-rendered branch. A prefetch uses
     // it to retain shared layouts and stop at the target loading boundary.
-    'next-url': location.pathname + location.search,
+    'next-url': options.fromUrl ?? locationKey(),
   }
   if (options.prefetch === 'auto') headers['next-router-prefetch'] = '1'
   // Only the streamed-navigation read path (readStreamedBody) can consume a
@@ -3413,7 +3716,7 @@ async function fetchPage(
  */
 async function fetchPageFrameNavigation(
   url: URL,
-  options: { navState?: DocumentNavState; sameUrl: boolean },
+  options: { navState?: DocumentNavState; sameUrl: boolean; fromUrl?: string },
 ): Promise<PrefetchedPage | null> {
   const policy = segmentCachePolicy
   // `output: 'export'` has no server to negotiate a frame with.
@@ -3431,7 +3734,7 @@ async function fetchPageFrameNavigation(
     'x-pnext-soft-nav': '1',
     'x-pnext-nav-state': encodeURIComponent(JSON.stringify(state)),
     'next-router-state-tree': encodeURIComponent(JSON.stringify(state)),
-    'next-url': location.pathname + location.search,
+    'next-url': options.fromUrl ?? locationKey(),
     [SEGMENT_PREFETCH_HEADER]: PAGE_SEGMENT_REQUEST_PATH,
   }
   const variant = `nav:${PAGE_SEGMENT_REQUEST_PATH}`
@@ -3531,6 +3834,10 @@ function recordSegmentEntry(input: {
     // and satisfies a sibling's prefetch without ever committing network-free.
     static: input.segmentPrerendered || input.shellPrerendered,
     runtime,
+    // The server TRUNCATED this response at its postponed boundary: the payload is this
+    // URL's own prerendered static stage, so a navigation may paint it however little of
+    // the page sits outside the holes. A runtime sample is not that - it is request data.
+    postponedShell: input.shellOnly && !runtime,
   })
 }
 
@@ -3660,13 +3967,20 @@ function mergeOutlinedHead(html: string, headFragment: string): string {
 // (anchorInlineSuspenseHoles). Return the first hole's parent plus the fallback nodes it
 // wraps, so the shell paint has the same anchor and source shape as the
 // `<pnext-suspense>` path.
-function inlineSuspenseRange(doc: Document): { anchor: Element; nodes: Node[] } | null {
-  const hole = doc.querySelector('pnext-hole[data-pnext-hole]')
+function inlineSuspenseRange(
+  doc: Document,
+): { anchor: Element; nodes: Node[]; hole: Element } | null {
+  // A loading.js hole carries the depth attribute the renderer lifted onto it; prefer it over
+  // an app `<Suspense>` hole exactly as the marker wire form prefers its stamped marker.
+  const hole =
+    doc.querySelector(`pnext-hole[data-pnext-hole][${LOADING_DEPTH_ATTRIBUTE}]`) ??
+    doc.querySelector('pnext-hole[data-pnext-hole]')
   if (!hole?.parentElement) return null
-  return { anchor: hole.parentElement, nodes: [...hole.childNodes] }
+  return { anchor: hole.parentElement, nodes: [...hole.childNodes], hole }
 }
 
-function showLoadingShell(
+/** Exported for the DOM-level unit test (see `paintStaticStageSubtree`). */
+export function showLoadingShell(
   shellHtml: string,
   sequence: number,
   target: URL,
@@ -3678,23 +3992,48 @@ function showLoadingShell(
    * STAGE so its fallbacks are unwrapped - committed content carries no stream wrappers.
    */
   allowWithoutBoundary = false,
+  /** The shell came from this navigation's live response at its commit boundary. */
+  allowResponseSuspense = false,
 ) {
   if (sequence !== navigationSequence) return false
   if (typeof DOMParser === 'undefined') return false
+  const paintHold = document.querySelector<HTMLElement>('[data-pnext-navigation-paint-hold]')
   const doc = new DOMParser().parseFromString(shellHtml, 'text/html')
   materializeClientIslandMarkers(doc)
-  const marker = doc.querySelector('pnext-suspense[data-pnext-suspense]')
+  // A STATIC STAGE owns whatever chunks streamed with it, so resolve them before picking what
+  // to paint - `paintStaticStageSubtree` already does, and painting the fallback of a boundary
+  // whose content is right there would put a placeholder on screen for content we hold.
+  if (allowWithoutBoundary || allowResponseSuspense) materializeStreamedSegments(doc)
+  // A shell can carry markers for BOTH a loading.js boundary and the app's own
+  // `<Suspense>`; prefer the loading.js one. Cached shells require that explicit route boundary,
+  // while a live response paints any hole still pending when its shell commits.
+  const marker =
+    doc.querySelector(`pnext-suspense[data-pnext-suspense][${LOADING_DEPTH_ATTRIBUTE}]`) ??
+    doc.querySelector('pnext-suspense[data-pnext-suspense]')
   const inline = marker ? null : inlineSuspenseRange(doc)
   const suspense = marker ?? inline?.anchor
   if (!suspense && !allowWithoutBoundary) return false
-  if (!loadingBoundaryChanges(marker, target)) return false
-  const { container, markerRange } = loadingShellTarget()
-  // A painted loading shell IS a committed navigation (pushOptimisticUrl moves the address
-  // bar the instant this returns true), so the window route state must reflect the
-  // DESTINATION before any island reads useParams - otherwise usePathname and useParams
-  // diverge and a history entry captures the new URL with the OLD params.
-  const shellRoute = predictedRoute ?? documentRouteState(doc)
-  if (shellRoute) window.__PNEXT_ROUTE__ = shellRoute
+  // Either wire form can carry the loading.js stamp; the hole is the inline form's marker.
+  const boundary = marker ?? inline?.hole ?? null
+  const loadingBoundary = isLoadingBoundaryMarker(boundary)
+  if (!allowWithoutBoundary && !loadingBoundary && !allowResponseSuspense) {
+    return false
+  }
+  if (!loadingBoundaryChanges(boundary, target)) return false
+  const { container: slotContainer, markerRange } = loadingShellTarget()
+  // `loadingShellTarget` degrades to <body> when the live document has no page slot - what a
+  // CLIENT layout leaves behind, its slot markers consumed by the Preact render. Painting there
+  // replaces the WHOLE live body with an inert copy: no preserved islands, no reused layout DOM.
+  // When the incoming slot sits inside an island the live document also mounts, the paint IS
+  // scopable after all - graft through that island (searchparams-reuse-loading reuses a
+  // prefetched loading state under a client layout). Otherwise wait for the payload, which
+  // grafts through `swapBody` with island preservation intact.
+  const scopedOwner =
+    !markerRange && slotContainer === document.body
+      ? liveOwnerOfIncomingSlot(doc, boundary ?? suspense ?? null)
+      : null
+  if (!markerRange && slotContainer === document.body && !scopedOwner) return false
+  const container = scopedOwner ?? slotContainer
   const fragment = document.createDocumentFragment()
   // The streamed document can already contain an ancestor layout that resolved before the
   // loading boundary. Keep that prefix when painting the fallback: replacing the target
@@ -3716,6 +4055,15 @@ function showLoadingShell(
           // nothing this paint could put on screen.
           null
   if (!sourceNodes) return false
+  // A painted loading shell IS a committed navigation (pushOptimisticUrl moves the address
+  // bar the instant this returns true), so the window route state must reflect the
+  // DESTINATION before any island reads useParams - otherwise usePathname and useParams
+  // diverge and a history entry captures the new URL with the OLD params.
+  const shellRoute = predictedRoute ?? documentRouteState(doc)
+  if (shellRoute) window.__PNEXT_ROUTE__ = shellRoute
+  // Past every bailout: this paint puts the destination on screen and commits the
+  // navigation, so its sheets go in with it rather than waiting for the payload.
+  void installStylesheets(doc)
   for (const node of sourceNodes) fragment.append(document.importNode(node, true))
   // A STATIC STAGE paints committed content, so its fallbacks land bare — the
   // wrappers are stripped from the COPY (the source doc keeps them, so the
@@ -3737,6 +4085,7 @@ function showLoadingShell(
   // useOffline(), say), and an unmounted island keeps its SSR value forever.
   // mountRoute is idempotent, so mounting on every paint is safe.
   mountPaintedIslands(doc)
+  if (paintHold) document.body.append(paintHold)
   return true
 }
 
@@ -3749,6 +4098,25 @@ function liveIslandOwner(node: Element): LiveIslandRoot | null {
   return root?.__pnextLive ? root : null
 }
 
+/**
+ * The MOUNTED island that owns the incoming document's page slot, when the live document
+ * mounts the same one. It is the paint target a consumed slot leaves behind: the shell
+ * re-renders through the island rather than over the whole body.
+ */
+function liveOwnerOfIncomingSlot(doc: Document, boundary: Element | null): LiveIslandRoot | null {
+  // A shell that suspended ABOVE its page slot ships no slot at all - the slot rides in the
+  // resolved chunk. The boundary itself then names the island the paint belongs to.
+  const incoming = (doc.getElementById('pnext-page') ?? boundary)?.closest(
+    'pnext-client[data-pnext-client]',
+  )
+  const id = incoming?.getAttribute('data-pnext-client')
+  if (!id) return null
+  const live: LiveIslandRoot | null = document.querySelector(
+    `pnext-client[data-pnext-client="${CSS.escape(id)}"]`,
+  )
+  return live?.__pnextLive ? live : null
+}
+
 /** `live`'s counterpart in an incoming document, matched on island id. */
 function incomingIslandFor(doc: Document, live: LiveIslandRoot): Element | null {
   const id = live.getAttribute('data-pnext-client')
@@ -3774,13 +4142,101 @@ function mountPaintedIslands(doc: Document) {
  * layout the live tree never rendered, a parallel-route slot beside the page) - those nodes
  * would be dropped. When the incoming stage carries such structure, take the real graft
  * path instead: `swapBody`, so root-layout DOM identity survives.
+ *
+ * Exported for the DOM-level unit test.
  */
-function commitStaticStage(html: string, sequence: number, target: URL): boolean {
+export function commitStaticStage(
+  html: string,
+  sequence: number,
+  target: URL,
+  /**
+   * Whether the server declared this a postponed shell. Under cacheComponents, Next treats this
+   * as the segment-cache commit and may paint its application fallback. Ordinary apps still need
+   * destination content beside the holes or an explicit loading.js boundary.
+   */
+  postponedShell = false,
+): boolean {
   if (sequence !== navigationSequence) return false
+  // cacheComponents' postponed stage is a real segment-cache commit, including
+  // an application Suspense fallback such as Next's mismatching-prefetch shell.
+  // Ordinary apps retain the stricter rule that prevented their root splash
+  // from painting merely because a shell arrived.
+  if (!staticStageIsRealContent(html, postponedShell && activityBfcacheEnabled())) return false
   if (paintStaticStageSubtree(html)) return true
   return showLoadingShell(html, sequence, target, undefined, true)
 }
 
+/**
+ * True when a cached static stage is the destination's REAL content rather than an app shell
+ * still waiting on its holes. `allowWithoutBoundary` exists for the fully prerendered stage,
+ * which carries no boundary at all; a stage whose page content is NOTHING but an unresolved
+ * `<Suspense>` fallback is a placeholder the dynamic payload replaces, and only a `loading.js`
+ * boundary may paint that early - exactly the rule the loading-shell path applies.
+ *
+ * A partially static stage - real content BESIDE its holes - is the destination's prerendered
+ * output, which Next paints as soon as it has it (segment-cache "serves cached static segments
+ * instantly on the second navigation").
+ */
+function staticStageIsRealContent(html: string, trustedPostponedShell = false): boolean {
+  // Cheap reject: no boundary wire form in the markup means nothing is unresolved.
+  if (!html.includes('data-pnext-suspense') && !html.includes('data-pnext-hole')) return true
+  if (trustedPostponedShell) return true
+  if (typeof DOMParser === 'undefined') return true
+  const doc = new DOMParser().parseFromString(html, 'text/html')
+  materializeClientIslandMarkers(doc)
+  // Boundaries whose chunk already streamed resolve here; whatever marker survives is a hole
+  // the dynamic stage still owes.
+  materializeStreamedSegments(doc)
+  // A hole stamped with the loading depth is a loading.js boundary, which may paint here for
+  // the same reason its marker form may: it is the wait Next itself shows.
+  const unresolved = [
+    ...doc.querySelectorAll(`pnext-hole[data-pnext-hole]:not([${LOADING_DEPTH_ATTRIBUTE}])`),
+    ...[...doc.querySelectorAll('pnext-suspense[data-pnext-suspense]')].filter(
+      marker => !isLoadingBoundaryMarker(marker),
+    ),
+  ]
+  return unresolved.length === 0 || stageCarriesContentBesideHoles(doc)
+}
+
+/** Elements that carry no page content of their own: wire hosts and document plumbing. */
+const STAGE_STRUCTURAL_ELEMENTS = new Set([
+  'script',
+  'template',
+  'style',
+  'link',
+  'pnext-suspense',
+  'pnext-hole',
+])
+
+/**
+ * True when the stage renders something of the destination's own OUTSIDE its unresolved
+ * boundaries - the partially static (PPR) shape. A stage whose page slot holds only boundary
+ * fallbacks is an app shell and keeps waiting.
+ */
+function stageCarriesContentBesideHoles(doc: Document): boolean {
+  const pageSlot = doc.getElementById('pnext-page')
+  if (
+    !pageSlot &&
+    doc.querySelector(
+      'pnext-client :is(pnext-hole[data-pnext-hole],pnext-suspense[data-pnext-suspense])',
+    )
+  ) {
+    // A boundary above the page slot postpones the client root that owns the page itself.
+    // Wrapper/static-child markup around that hole is not an independently paintable PPR
+    // segment; the page slot only materializes with the continuation.
+    return false
+  }
+  const slot = pageSlot ?? doc.body
+  if (!slot) return false
+  for (const element of slot.querySelectorAll('*')) {
+    if (STAGE_STRUCTURAL_ELEMENTS.has(element.localName)) continue
+    if (element.closest('pnext-suspense[data-pnext-suspense], pnext-hole[data-pnext-hole]'))
+      continue
+    return true
+  }
+  return false
+}
+
 /**
  * Replace every `<pnext-suspense>` fallback wrapper with the fallback itself. The renderer
  * wraps a boundary's fallback so the streaming runtime can promote the resolved chunk over
@@ -3807,6 +4263,7 @@ function unwrapSuspenseFallbacks(root: ParentNode): void {
  */
 export function paintStaticStageSubtree(html: string): boolean {
   if (typeof DOMParser === 'undefined') return false
+  const paintHold = document.querySelector<HTMLElement>('[data-pnext-navigation-paint-hold]')
   const doc = new DOMParser().parseFromString(html, 'text/html')
   if (!isPNextDocument(doc)) return false
   // Materialize BEFORE comparing structure: the renderer ships the page slot (and
@@ -3815,6 +4272,9 @@ export function paintStaticStageSubtree(html: string): boolean {
   materializeClientIslandMarkers(doc)
   materializeStreamedSegments(doc)
   if (!staticStageFrameGrows(doc)) return false
+  // This paint COMMITS the navigation, so the destination's sheets belong on the document
+  // now; the commit below re-reads them from its own doc and waits out these loads.
+  void installStylesheets(doc)
   unwrapSuspenseFallbacks(doc)
   // A painted static stage IS a committed navigation (see showLoadingShell):
   // the window route state must describe the destination before any island
@@ -3837,6 +4297,7 @@ export function paintStaticStageSubtree(html: string): boolean {
   // against the tree painted here. `swapBody`'s own body-child reuse still applies.
   swapBody(doc)
   mountPaintedIslands(doc)
+  if (paintHold) document.body.append(paintHold)
   return true
 }
 
@@ -3907,13 +4368,31 @@ function frameDescriptor(element: Element): string {
 /** Attribute the renderer stamps with a loading boundary's guarded URL depth. */
 const LOADING_DEPTH_ATTRIBUTE = 'data-pnext-loading-depth'
 
+/**
+ * True when a shell's boundary is a `loading.js` one — the ONLY boundary Next may swap in
+ * before the navigation payload lands. The renderer stamps the URL depth on exactly those
+ * markers, so the attribute IS the signal: a plain `<Suspense>` the app wrote in a layout
+ * (or in the page) carries none, and its fallback belongs to the incoming render, not to
+ * the wait for it. Painting one over the departing page empties the body a whole request
+ * early, where Next keeps the previous route interactive.
+ *
+ * The inline-suspense wire form (`<pnext-hole>`, rewritten from preact's stream comments)
+ * gets the same stamp lifted onto it from the fallback's leading depth marker, so a
+ * loading.js boundary proves itself in both wire forms; an app `<Suspense>` in either
+ * carries nothing and never paints a fallback.
+ */
+function isLoadingBoundaryMarker(marker: Element | null): boolean {
+  return marker?.hasAttribute(LOADING_DEPTH_ATTRIBUTE) === true
+}
+
 /**
  * True when the loading boundary carried by a shell owns a segment INSIDE the subtree this
  * navigation changes, so its fallback may paint. A loading.js boundary re-arms only when
  * the segment it directly guards changes; the server stamps each boundary's URL depth on
  * its marker, and when the live and target children paths diverge DEEPER than that the
  * boundary belongs to a preserved shared ancestor and painting it would flash a loading
- * state Next never shows. Shells without the attribute keep painting.
+ * state Next never shows. A STATIC STAGE paints committed content rather than a fallback,
+ * so its (possibly absent) marker imposes no such gate.
  */
 function loadingBoundaryChanges(marker: Element | null, target: URL): boolean {
   const raw = marker?.getAttribute(LOADING_DEPTH_ATTRIBUTE)
@@ -3955,7 +4434,7 @@ async function pageForNavigation(
    * out. Unlike `onShell` this markup is not a loading fallback but the route's real static
    * content, so it paints with or without a boundary.
    */
-  onStaticStage?: (html: string) => void,
+  onStaticStage?: (html: string, postponedShell?: boolean) => void,
   /** The segment-cache hit `softNavigate` already looked up for this URL. */
   segmentHit?: SegmentCacheHit | null,
   /**
@@ -3963,6 +4442,8 @@ async function pageForNavigation(
    * paint could swap the live one. Cached entries are matched against it, never the live one.
    */
   departureNavState: DocumentNavState = currentNavState(),
+  /** The rendered origin route; unlike location this still names the departure on popstate. */
+  departureUrl: string = locationKey(),
   /**
    * This navigation may ask for the `/_page` frame alone when the policy says the layout
    * chain is already in hand. Decided by `softNavigate` (it owns the departing URL/state)
@@ -3975,14 +4456,14 @@ async function pageForNavigation(
   // At most one static stage paints per navigation: an attached prefetch's
   // shell and a segment-cache hit are two views of the same content.
   let staticStagePainted = false
-  const paintStaticStage = (html: string) => {
+  const paintStaticStage = (html: string, postponedShell = false) => {
     if (staticStagePainted) return
     staticStagePainted = true
     // A cached stage with parallel slots has dynamic continuations beside the page. Those cannot
     // be reconstructed from a page-only frame, so this navigation needs the whole target document.
     if (html.includes('data-pnext-slot=') || slotStateSensitive(departureNavState, html))
       pageFrame.eligible = false
-    onStaticStage?.(html)
+    onStaticStage?.(html, postponedShell)
   }
   const cached = prefetchEntriesForNavigation(key).find(
     entry =>
@@ -4014,7 +4495,9 @@ async function pageForNavigation(
     // Attached to an in-flight (or already settled) SHELL prefetch for this exact target:
     // the navigation issued no duplicate fetch, so paint the static stage it landed and let
     // the dynamic stage stream in below.
-    if (page?.shellOnly) paintStaticStage(page.html)
+    // A shell-only prefetch IS the server's postponed shell for this URL (its headers are what
+    // `shellOnly` reads), so it paints like the PPR stage it is.
+    if (page?.shellOnly) paintStaticStage(page.html, true)
     if (!page) {
       for (const full of [true, false]) {
         const cacheKey = prefetchCacheKey(key, full)
@@ -4054,7 +4537,8 @@ async function pageForNavigation(
   // Partial paint (Segment-M2 fix-forward 1): a cached static segment that may
   // NOT commit on its own still paints now, so the route's static content is on
   // screen while the dynamic stage below streams the remainder in.
-  if (segmentHit && !segmentHit.networkFree) paintStaticStage(segmentHit.html)
+  if (segmentHit && !segmentHit.networkFree)
+    paintStaticStage(segmentHit.html, segmentHit.postponedShell === true)
   // Per-segment navigation: `/_page` alone, composed with the cached layout.
   // Null (policy declined, miss, anything unexpected) falls through to the
   // whole-document fetch below unchanged.
@@ -4062,12 +4546,14 @@ async function pageForNavigation(
     ? await fetchPageFrameNavigation(url, {
         navState: options.navState ?? departureNavState,
         sameUrl: pageFrame.sameUrl,
+        fromUrl: departureUrl,
       }).catch(() => null)
     : null
   const page =
     framed ??
     (await fetchPage(url.href, {
       navState: options.navState ?? departureNavState,
+      fromUrl: departureUrl,
       onShell,
     }).catch(() => null))
   // Visited-page seeding: the navigation response is as fresh as any prefetch —
@@ -4197,15 +4683,28 @@ function seedNavigationEntry(
 }
 
 /**
- * The document's own PRE-HYDRATION shell, stashed by the streaming runtime at the first
- * chunk boundary. `captureHardLoad` serializes the LIVE DOM at the load event - after every
+ * The document's own PRE-HYDRATION shell, stashed by the document bootstrap before island
+ * hydration (or by the streaming runtime if a continuation promotes first). `captureHardLoad`
+ * otherwise sees the LIVE DOM at the load event - after every
  * streamed chunk has been promoted over its fallback - so a PPR document reads back as
- * settled and `sliceShell` finds no cut. The stash exists ONLY for a document that actually
- * streamed a continuation, which is exactly the case the slice can no longer detect.
+ * settled and `sliceShell` finds no cut.
  */
 function preHydrationShell(): string | undefined {
-  const stashed = (window as { __PNEXT_SHELL_HTML__?: unknown }).__PNEXT_SHELL_HTML__
-  return typeof stashed === 'string' && stashed.length > 0 ? stashed : undefined
+  const stashed = (window as { __PNEXT_SHELL_HTML__?: string }).__PNEXT_SHELL_HTML__
+  // If a promotion script won the capture race, one or more dynamic continuations already sit in
+  // the markup. Those carry the loaded URL's resolved content, so anything replaying this stage -
+  // a sibling param reusing it across an empty vary set - would paint that URL's data. Drop any
+  // carriers; the document-bootstrap zero-stream case simply has none.
+  return stashed && stripStreamChunks(stashed)
+}
+
+/** `html` without the hidden `<div data-pnext-stream>` carriers of its streamed continuations. */
+function stripStreamChunks(html: string): string {
+  const doc = new DOMParser().parseFromString(html, 'text/html')
+  const chunks = doc.querySelectorAll('div[hidden][data-pnext-stream]')
+  if (!chunks.length) return html
+  for (const chunk of chunks) chunk.remove()
+  return `<!doctype html>${doc.documentElement.outerHTML}`
 }
 
 /**
@@ -4252,12 +4751,14 @@ function recordNavigationSegment(
   if (hardLoad && runtimeDocument) return
   const hint = documentStaticHintFromHtml(page.html)
   const shell = staticStage ?? sliceShell(page.html, page.shellOnly === true)
-  // A HARD LOAD whose stashed pre-hydration stage came out of a BAKED SHELL is a prerender,
-  // and the server published the shell's vary set alongside the flag, so the entry keys
-  // across the route's params. Both halves are required: the flag alone would promote a
-  // sliced dynamic stream, the stash alone cannot prove the bytes are baked. The entry stays
-  // INCOMPLETE, so a navigation onto it still fetches its own dynamic remainder.
-  const bakedStaticStage = staticStage !== undefined && hint?.staticStage === true
+  // A document resumed from a BAKED SHELL is a prerender, and the server published that
+  // shell's vary set alongside the flag, so the entry keys across the route's params. Both
+  // halves are required: the flag alone (with no stage in hand) proves nothing, and a stage
+  // without it is a sliced dynamic stream. The stage is whichever the router holds - a hard
+  // load's stashed pre-hydration prefix, or the slice of a streamed navigation response,
+  // which cuts at exactly the boundary the server postponed at. The entry stays INCOMPLETE,
+  // so a navigation onto it still fetches its own dynamic remainder.
+  const bakedStaticStage = (staticStage ?? shell) !== null && hint?.staticStage === true
   const isStatic = page.segmentPrerendered === true || hint?.isStatic === true || bakedStaticStage
   if (shell === null && !isStatic) return
   const staleTimeMs = prefetchStaleTimeMs({
@@ -4289,6 +4790,7 @@ function recordNavigationSegment(
     complete: shell === null,
     static: isStatic,
     runtime: false,
+    postponedShell: bakedStaticStage,
   })
 }
 
@@ -4384,8 +4886,14 @@ export function navStateKey(state: DocumentNavState): string {
 let navigationSequence = 0
 let suppressImmediateRefresh = false
 
+/** Current navigation generation, exposed so DOM-level paint tests retain the stale-work guard. */
+export function currentNavigationSequence(): number {
+  return navigationSequence
+}
+
 export async function softNavigate(href: string, options: SoftNavigateOptions = {}) {
   emitNavigationStart()
+  const departingEntrySrc = entryScriptSrc(document)
   // The entry being left (on popstate, history already points at the target,
   // so the live document's entry id is the tracked active one).
   const departingBfcacheId = options.pop ? activeBfcacheId : (historyBfcacheId() ?? activeBfcacheId)
@@ -4401,27 +4909,50 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // subtree (commitStaticStage) swaps the live `#__PNEXT_NAV_STATE__` for the
   // destination's, and reading it after that would report the incoming path as
   // the previous one (mis-classifying the nav as slot-only, killing the scroll).
-  const previousChildrenPath = currentNavState().children
   // The DEPARTING parallel-route state, likewise read before anything can paint. Every "may
   // this cached entry serve this navigation?" question is asked about the state the navigation
   // STARTED from. An optimistic loading-shell paint swaps the live `#__PNEXT_NAV_STATE__` for
   // the destination's, so re-reading after it would compare the navigation's own prefetch
   // against the target's state and reject it - re-fetching a route it had already prefetched.
   const departureNavState = currentNavState()
+  const previousChildrenPath = departureNavState.children
+  // `next-url` names the children tree the current document actually renders,
+  // which can differ from the browser URL after middleware rewrites. Keep this
+  // separate from `departingRouteKey`: the latter is intentionally the visible
+  // pathname+search used by history/document caches.
   // Back/forward cache (Next's bfcache): the route being left, keyed by
   // pathname+search. On popstate `location` already points at the target, so
   // the departing route is the last committed one (`routerState.activeRouteKey`); on a
   // link/push nav it is simply the current location. Its stateful island roots
   // are stashed under this key below so returning to it (via link OR history
   // traversal) restores React state.
-  const departingRouteKey = options.pop
-    ? routerState.activeRouteKey
-    : bfRouteKey(location.pathname, location.search)
+  const departingRouteKey = options.pop ? routerState.activeRouteKey : locationKey()
+  const departureUrl = departureNavState.hostRender
+    ? departingRouteKey
+    : previousChildrenPath! + (departureNavState.childrenSearch ?? previousSearch)
   const url = resolveSoftUrl(href)
   if (!url) {
     hardNavigate(href, options.replace || options.pop)
     return
   }
+  // Resolve a traversal's document in the same place as every other navigation source. popstate
+  // supplies only the target history state; this chooser owns the decision between that entry's
+  // immutable restore source and the normal cache/fetch path. `cachedPage` remains an explicit
+  // injection point for focused DOM tests and callers that already hold a completed source.
+  const entryRestorePage = options.pop
+    ? entryDocCache.get(historyState().__pnextEntry as string)
+    : undefined
+  // A hard-loaded streaming document is cached from its immutable pre-hydration source. When that
+  // source contains a boundary whose continuation had not parsed yet, it is a static/loading stage,
+  // not a complete history document. Committing it on pop would bypass pageForNavigation entirely,
+  // so no request could ever deliver the missing continuation and the entry would remain loading.
+  // Keep explicit cachedPage injections unchanged for focused callers, but make an incomplete
+  // entry-bound source fall through to the ordinary pop fetch.
+  const restorePage =
+    options.cachedPage ??
+    (entryRestorePage && !streamHasPendingHole(entryRestorePage.html)
+      ? entryRestorePage
+      : undefined)
   // Client-instrumentation transition hook (Next's onRouterTransitionStart).
   ;(
     window as { __PNEXT_ON_ROUTER_TRANSITION_START__?: (href: string, kind: string) => void }
@@ -4465,6 +4996,11 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // Snapshot plain root-layout DOM before a cached/streamed shell can detach it. The final swap
   // reconciles onto these nodes so server layouts keep the same identity Next's root reconciler does.
   const departingReusableBody = reusableBodyChildren()
+  // Capture the complete outgoing screen before any loading/static stage can replace it. The
+  // resolved client-root commit uses this copy only while its first complete paint settles.
+  const paintHoldScrollTop =
+    document.querySelector<HTMLElement>('[data-scroll-root]')?.scrollTop ?? 0
+  const paintHold = createNavigationPaintHold()
   // Painting a prefetched loading shell IS a committed navigation, so push the requested URL
   // here and let usePathname() and the address bar reflect the destination while the fetch is
   // still in flight; the final commit replaces this entry with the resolved one (or, on a
@@ -4475,6 +5011,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // shallow same-entry move in onPopState and get dropped, stranding the UI on the
   // half-committed target. The commit below reuses the id.
   let optimisticEntryId: string | undefined
+  let optimisticBfcacheId: string | undefined
   // `silent` moves the address bar without broadcasting: used before the tree is painted, where a
   // location broadcast would render the destination URL against the departing route's params.
   const pushOptimisticUrl = (silent = false) => {
@@ -4482,7 +5019,21 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
     if (url.pathname === location.pathname && url.search === location.search) return
     optimisticallyPushed = true
     optimisticEntryId = routerState.renderedEntryId = newEntryId()
-    const shellState = { ...historyState(), __pnextEntry: optimisticEntryId }
+    // The loading/static stage publishes the destination URL immediately. Give
+    // that render the destination's state identity too; otherwise useRouter
+    // observes the new pathname with the departing bfcacheId, and the final
+    // same-URL broadcast cannot make a keyed leaf reset.
+    optimisticBfcacheId = nextBfcacheIdForNavigation(url, previousPathname)
+    // A PAINTED optimistic entry's document is what is on screen from here on; keep the
+    // live-entry pointer in step, or a traversal in this window snapshots the DESTINATION's
+    // DOM under the departing entry's id and destroys that entry's form-state capture. The
+    // silent (pre-paint) push leaves the pointer alone — the departing DOM is still live.
+    if (!silent) activeBfcacheId = optimisticBfcacheId
+    const shellState = {
+      ...historyState(),
+      __pnextEntry: optimisticEntryId,
+      [HISTORY_BFCACHE_ID_KEY]: optimisticBfcacheId,
+    }
     const move = () => {
       if (options.replace) history.replaceState(shellState, '', url.href)
       else history.pushState(shellState, '', url.href)
@@ -4505,12 +5056,19 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // server-side, and re-painting would replace a committed loading state with a second,
   // different one. A segment's loading fallback commits ONCE per navigation.
   let cachedStagePainted = false
+  const devSoftNavigation = isDevDocument()
   const onShell =
-    options.cachedPage || options.pop || refreshLike
+    restorePage || options.pop || refreshLike
       ? undefined
       : (shellHtml: string) => {
           if (cachedStagePainted) return
-          if (!showLoadingShell(shellHtml, sequence, url)) return
+          if (devSoftNavigation) return
+          // In dev, compilation can suspend an application boundary even though the route's real
+          // content is otherwise ready. Keep the departing page until that compile-only hole is
+          // resolved; an explicit loading.js boundary remains paintable through the ordinary
+          // loading-boundary path. Production retains streamed application-Suspense behavior.
+          const devNavigation = shellHtml.includes('data-pnext-dev')
+          if (!showLoadingShell(shellHtml, sequence, url, undefined, false, !devNavigation)) return
           // A loading boundary is a committed navigation state.
           pushOptimisticUrl()
           scheduleNavigationScroll(url, options)
@@ -4519,7 +5077,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // whether the generic loading shell should paint (a real cached static segment is strictly
   // better) and, in pageForNavigation, whether the navigation commits network-free.
   const segmentHit =
-    options.cachedPage || options.pop || refreshLike || slotStateSensitive(currentNavState())
+    restorePage || options.pop || refreshLike || slotStateSensitive(currentNavState())
       ? null
       : (segmentCachePolicy?.take({
           pathname: url.pathname,
@@ -4529,8 +5087,9 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // Paint a cached STATIC STAGE — the route's own content, not a fallback — and
   // treat it as a committed navigation exactly like a loading shell.
   const onStaticStage = onShell
-    ? (html: string) => {
-        if (!commitStaticStage(html, sequence, url)) return
+    ? (html: string, postponedShell = false) => {
+        if (devSoftNavigation) return
+        if (!commitStaticStage(html, sequence, url, postponedShell)) return
         cachedStagePainted = true
         pushOptimisticUrl()
         scheduleNavigationScroll(url, options)
@@ -4544,6 +5103,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // paint a sibling's layout while the destination layout is still on the wire.
   if (
     onShell &&
+    !devSoftNavigation &&
     !refreshLike &&
     !segmentHit &&
     !segmentCachePolicy?.needsLayoutFrameOnly?.({
@@ -4587,12 +5147,12 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // The document is still valid data for its own route, so it stays in the bfcache instead of
   // dying with the navigation. Never for a cached entry: re-storing one resets its commit time.
   const abandonFetchedPage = (fetched: PrefetchedPage | null | undefined) => {
-    if (!fetched || options.cachedPage) return
+    if (!fetched || restorePage) return
     const settled = new URL(fetched.finalUrl, location.href)
     storeBfDoc(bfRouteKey(settled.pathname, settled.search), fetched)
   }
   let page =
-    options.cachedPage ??
+    restorePage ??
     (await pageForNavigation(
       url,
       { ...options, refreshLike },
@@ -4600,6 +5160,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
       onStaticStage,
       segmentHit,
       departureNavState,
+      departureUrl,
       pageFrame,
     ))
   if (sequence !== navigationSequence) return abandonFetchedPage(page)
@@ -4632,7 +5193,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // refetch with the full-render header. A cached history entry has no server to refetch from
   // as far as this navigation is concerned - the document IS the entry's own render.
   if (
-    !options.cachedPage &&
+    !restorePage &&
     skippedSegmentsUngraftable(
       doc,
       options.freshSegments || cachedStagePainted || (refreshLike && !options.pageRefresh),
@@ -4640,6 +5201,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   ) {
     const fullPage = await fetchPage(url.href, {
       navState: options.navState,
+      fromUrl: departureUrl,
       fullRender: true,
     }).catch(() => null)
     if (sequence !== navigationSequence) return abandonFetchedPage(fullPage ?? page)
@@ -4675,14 +5237,33 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // then paints styled content immediately instead of flashing unstyled HTML.
   const entrySrc = entryScriptSrc(doc)
   warmEntryChunks(doc)
-  const [entryModule] = await Promise.all([
-    entrySrc ? importEntry(entrySrc) : Promise.resolve(null),
-    addStylesheets(doc),
-  ])
-  if (sequence !== navigationSequence) return abandonFetchedPage(page)
+  // A restored traversal with warm modules and settled stylesheets commits in the popstate
+  // task itself: the browser (and Next's in-memory router) treat back/forward as synchronous,
+  // so a reader immediately after history.back() must observe the target document. Awaiting
+  // here — even already-resolved promises — pushes the swap at least a task later and loses
+  // that footrace. Everything upstream of this point is synchronous when restorePage is set.
+  const pendingStylesheets = installStylesheets(doc)
+  let entryModule = entrySrc ? (entryModuleCache.get(entryModuleHref(entrySrc)) ?? null) : null
+  let departingEntryModule = departingEntrySrc
+    ? (entryModuleCache.get(entryModuleHref(departingEntrySrc)) ?? null)
+    : null
+  const warmPop =
+    options.pop &&
+    Boolean(restorePage) &&
+    pendingStylesheets.length === 0 &&
+    (entryModule !== null || !entrySrc) &&
+    (departingEntryModule !== null || !departingEntrySrc)
+  if (!warmPop) {
+    ;[entryModule, departingEntryModule] = await Promise.all([
+      entrySrc ? importEntry(entrySrc) : Promise.resolve(null),
+      departingEntrySrc ? importEntry(departingEntrySrc) : Promise.resolve(null),
+      Promise.all(pendingStylesheets),
+    ])
+    if (sequence !== navigationSequence) return abandonFetchedPage(page)
+  }
 
   if (!options.pop) {
-    const bfcacheId = nextBfcacheIdForNavigation(targetUrl, previousPathname)
+    const bfcacheId = optimisticBfcacheId ?? nextBfcacheIdForNavigation(targetUrl, previousPathname)
     const entryState = {
       ...historyState(),
       // The shell push already minted this entry's id; keep it so the resolved
@@ -4708,11 +5289,27 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
     else history.pushState(entryState, '', committedHref)
   }
 
+  // Install the final document's route snapshot before any preserved island is reconciled.
+  // A full popstate intentionally does not publish its address-bar change while the departing
+  // tree is still live; this snapshot keeps useParams paired with the URL when mountRoute renders
+  // that island for the committed tree. Forward commits need the same ordering when no loading or
+  // static stage painted an earlier destination snapshot.
+  // Compare against the departing route before publishing the incoming route
+  // state. Once window.__PNEXT_ROUTE__ is replaced, routeParamBoundaryChanged
+  // would compare the destination with itself and hide every param transition.
+  const parallelSlotsChanged = navSlotsChanged(doc)
+  const remountPageIslands =
+    (options.pop && !parallelSlotsChanged) || routeParamBoundaryChanged(doc)
+  const committedRoute = documentRouteState(doc)
+  if (committedRoute) window.__PNEXT_ROUTE__ = committedRoute
+
   // Template semantics: a client template island REMOUNTS (fresh state) when
   // the segment it wraps navigates to a different path, and is preserved like
   // a layout island otherwise (refresh, search-param-only and slot-only navs).
   const remountTemplates = docNavStateChildren(doc, targetUrl.pathname) !== previousChildrenPath
-  const remountPageIslands = routeParamBoundaryChanged(doc)
+  // Page effects are entry-scoped. In particular, an app's popstate-gated initializer must run
+  // again on cached back; reattaching the old live page root skips that initializer. Different
+  // children routes likewise mount fresh even when two pages happen to use the same island id.
   // Shared-layout state preservation: live island roots that render again in the incoming
   // document keep their DOM (and component state) across the swap. Server-segment
   // preservation keeps live layout DOM and refreshes only the page slot. Parallel-route slot
@@ -4728,10 +5325,30 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
     options.freshSegments ||
     cachedStagePainted ||
     (refreshLike && !options.pageRefresh) ||
-    navSlotsChanged(doc)
+    parallelSlotsChanged
       ? (clearSegmentPreserveTags(doc), [])
       : matchPreservedServerSegments(doc)
   const preservedIslands = matchPreservedIslands(doc, remountTemplates, remountPageIslands)
+  // A missing live page marker alone is not enough: ordinary server layouts also consume their
+  // marker after mount. The slotless lifecycle path is specifically for a preserved client-layout
+  // island whose incoming placeholder owns the page marker that its live tree adopted.
+  const slotlessClientRootLayout = hasSlotlessClientRootLayout(doc, preservedIslands)
+  // A cacheComponents tree follows Next's Activity lifecycle: the inactive page
+  // stays mounted. The explicit empty-page pass exists only for ordinary apps,
+  // whose outgoing page must unmount while its DOM is still connected.
+  // On a traversal, the browser has already fired popstate. A synthetic empty-page
+  // render would remount layout effects against the departing URL and let them
+  // consume that signal before the destination page can initialize from it. The
+  // final mount still reconciles the outgoing page while its preserved shell is
+  // connected. Forward navigations retain the explicit pass so their cleanup can
+  // snapshot the departing page before the swap.
+  const unmountSlotlessPage = slotlessClientRootLayout && !activityBfcacheEnabled() && !options.pop
+  if (unmountSlotlessPage) {
+    keySlotlessClientPage(
+      doc,
+      `${targetUrl.pathname}${targetUrl.search}|${historyBfcacheId() ?? ''}`,
+    )
+  }
   const preservedPage = matchPreservedClientPage(
     doc,
     (refreshLike || sameRouteQueryNav(doc)) && !options.remount,
@@ -4744,11 +5361,22 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
     ...preservedIslands,
     ...preservedSegmentIslands(preservedSegments),
   ])
+  // A client root layout can consume the page slot during hydration, leaving its route screens as
+  // top-level island roots beside the preserved shell islands. Absence from #pnext-page must not
+  // promote those unmatched screens into layout cache entries: they are page lifecycle owners and
+  // must unmount while the live shell (and its scroll container) is still attached. The shared roots
+  // are already identified above by matching an incoming placeholder and remain preserved.
   // Back/forward cache - stash BEFORE restore, so the fixed-size eviction sees the true entry
   // count (page 1 evicts on the 4th visit even though that same navigation restores page 2).
   // Keeping the departing roots alive and adding them to keptIslands makes the unmount below
   // skip them, so a later return restores their React state.
-  const departingRoots = departingLiveRoots.filter(root => !keptLiveIslands.has(root))
+  const preserveInactiveTree = activityBfcacheEnabled()
+  const departingRoots = preserveInactiveTree
+    ? departingLiveRoots.filter(root => !keptLiveIslands.has(root))
+    : []
+  // Only shared-layout roots belong in pnext's live-root cache. Page roots must be unmounted by
+  // the outgoing entry while still attached (so effect cleanups can read/save DOM state), then the
+  // destination source mounts a fresh root after the swap.
   if (departingRouteKey && departingRouteKey !== targetRouteKey) {
     stashRouteRoots(departingRouteKey, departingRoots)
   }
@@ -4758,9 +5386,8 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // cacheComponents (Next's link-navigation bfcache ships with the client segment cache); a
   // classic app remounts instead, so a re-revealed accordion starts closed again. History
   // traversal restores either way.
-  const bfcacheRestores = options.pop || segmentSchedulerEnabled()
   const restoredIslands =
-    refreshLike || !bfcacheRestores
+    refreshLike || !preserveInactiveTree
       ? []
       : matchRouteCachedIslands(doc, targetRouteKey, preservedIslands.length, remountTemplates)
   const keptIslands = new Set<Element>([...keptLiveIslands, ...restoredIslands])
@@ -4769,68 +5396,157 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // page slot is a marker-range proxy); the entry's unmount compares roots by
   // identity, so it rides the same set.
   if (preservedPage) keptIslands.add(preservedPage.root as unknown as Element)
+  // Wake route-keyed layout children while the departing DOM is still attached. Their layout
+  // cleanups can save shell state before unmount/swap; pop mounts the destination first instead.
   window.__PNEXT_ACTIVE_ENTRY__?.unmount?.(keptIslands)
-  syncHeadMetadata(doc)
-  // Next reconciles the DOM in place, so a focused element in a retained layout keeps focus
-  // across a navigation. pnext's swap DETACHES preserved subtrees to graft them into the new
-  // body, and detaching blurs - remember the focused node so it can be refocused.
-  const focusedBeforeSwap = document.activeElement
-  swapBody(
-    doc,
-    [...preservedIslands, ...restoredIslands],
-    preservedSegments,
-    preservedPage,
-    departingReusableBody,
-  )
-  stylesheetReconciler?.(doc)
-  // The swapped document carries the render's parallel-route state; pin it
-  // (plus the document itself) to this history entry so back/forward restores
-  // what was actually shown, without a server round trip.
-  storeNavState()
-  cacheEntryDocument(page)
-  // The committed document is a shown-route snapshot: a later full prefetch of
-  // this route reads it from the bfcache instead of the network.
-  storeBfDoc(targetRouteKey, page)
-  // This route is now the committed one — the next navigation's departing key.
-  routerState.activeRouteKey = targetRouteKey
-
-  await entryModule?.mountRoute?.()
-  if (sequence !== navigationSequence) return
-  restoreSwapFocus(focusedBeforeSwap)
-  if (!options.pop && departingBfcacheId && previousPathname !== targetUrl.pathname) {
-    restoreSharedLayoutFormState(departingBfcacheId, previousPathname, targetUrl.pathname)
+  let focusedBeforeSwap: Element | null = null
+  let navigationFocusTarget: HTMLElement | null = null
+  try {
+    if (unmountSlotlessPage && departingRouteKey && departingRouteKey !== targetRouteKey) {
+      // Cover the lifecycle-only empty-page pass. This is the same outgoing screen clone used for
+      // the final atomic commit, attached early enough that no empty intermediate frame can paint.
+      attachNavigationPaintHold(paintHold, paintHoldScrollTop, sequence)
+      await unmountSlotlessClientPage(
+        doc,
+        preservedIslands,
+        departingEntryModule,
+        departingRouteKey,
+      )
+      if (sequence !== navigationSequence) return
+    }
+    syncHeadMetadata(doc)
+    // Next reconciles the DOM in place, so a focused element in a retained layout keeps focus
+    // across a navigation. pnext's swap DETACHES preserved subtrees to graft them into the new
+    // body, and detaching blurs - remember the focused node so it can be refocused.
+    focusedBeforeSwap = document.activeElement
+    swapBody(
+      doc,
+      [...preservedIslands, ...restoredIslands],
+      preservedSegments,
+      preservedPage,
+      departingReusableBody,
+    )
+    attachNavigationPaintHold(paintHold, paintHoldScrollTop, sequence)
+    // A client root layout adopts and dissolves the page-slot markers during
+    // mount. Resolve Next's segment scroll target against the freshly swapped
+    // document while those markers still identify the changed page.
+    const slotOnlyNav =
+      currentNavState().children === previousChildrenPath &&
+      url.search === previousSearch &&
+      // A changed pathname is only slot-only when the parallel-slot state
+      // actually changed. This remains decidable when a body-owned client shell
+      // has already removed the departing entry's route script.
+      (targetUrl.pathname === previousPathname || parallelSlotsChanged) &&
+      !remountPageIslands
+    const navigationScrollOptions = {
+      ...options,
+      scroll:
+        targetUrl.pathname !== previousPathname && !parallelSlotsChanged
+          ? options.scroll
+          : slotOnlyNav
+            ? false
+            : options.scroll,
+    }
+    // Resolve the changed segment while the freshly swapped document still has
+    // its page markers. A body-owning client root dissolves those markers during
+    // mount, after which the compat scroll walk can only see the broad shell.
+    scheduleNavigationScroll(url, navigationScrollOptions)
+    const focusedByNavigation = document.activeElement
+    if (
+      focusedByNavigation instanceof HTMLElement &&
+      focusedByNavigation !== document.body &&
+      focusedByNavigation !== document.documentElement &&
+      focusedByNavigation !== focusedBeforeSwap
+    ) {
+      navigationFocusTarget = focusedByNavigation
+    }
+    stylesheetReconciler?.(doc)
+    // Finish the stylesheet transaction in the same synchronous DOM turn as the body swap. A
+    // selector waiter can observe the destination immediately after this stack unwinds; pruning in
+    // the later post-mount phase let it catch the target node between its correct route sheet and a
+    // stale asynchronous prune from the preceding navigation.
+    if (!url.hash) pruneStylesheets(doc)
+    // The swapped document carries the render's parallel-route state; pin it
+    // (plus the document itself) to this history entry so back/forward restores
+    // what was actually shown, without a server round trip.
+    storeNavState()
+    cacheEntryDocument(page)
+    // The committed document is a shown-route snapshot: a later full prefetch of
+    // this route reads it from the bfcache instead of the network.
+    storeBfDoc(targetRouteKey, page)
+    // This route is now the committed one — the next navigation's departing key.
+    routerState.activeRouteKey = targetRouteKey
+    pingVisiblePrefetchLinks()
+    // Browser form restoration is part of the traversal itself: fill the swapped (raw,
+    // pre-hydration) controls in the same synchronous turn as the swap, so a reader right after
+    // history.back() sees the values. The post-effects pass below still handles controls a
+    // mount rebuilds, and only ever fills empty ones.
+    if (options.pop) restoreFormState(historyBfcacheId())
+
+    if (page.p) (window as typeof window & { __PNEXT_PROPS__?: unknown }).__PNEXT_PROPS__ = page.p
+    await entryModule?.mountRoute?.()
+    // The mount can recreate the controls the pre-mount fill above populated. Re-fill before
+    // flushClientEffects' settling FRAME below — deferring past it shows a traversal with
+    // empty controls for a full frame, which a reader right after history.back() observes.
+    if (options.pop && sequence === navigationSequence) restoreFormState(historyBfcacheId())
+    // Compat batches layout-effect disposal to the end of the Preact commit. Let that disposal run
+    // before usePathname wakes the preserved PageTransition's destination effect (which resets the
+    // shared shell scroll position). The old screen and its scroll container are still connected.
+    await flushClientEffects()
+    // Publish the committed URL while the paint hold still covers the new tree. Preserved client
+    // layouts key their routed child on usePathname/useSearchParams; waking that store is what gives
+    // the outgoing child a real cleanup and the destination a fresh initializer. Keeping the hold
+    // through the following frame makes that keyed replacement atomic in dev as well as production.
+    if (sequence === navigationSequence) {
+      // Commit listeners run first: loaders may deliberately remain visible until the location
+      // subscriber observes the matching tree (the same ordering as the former end-of-commit pair).
+      emitNavigationCommit()
+      emitLocationChange()
+      // History traversal restores the popped entry's form state over the freshly mounted tree
+      // (browser back/forward form restoration semantics). This runs BEFORE the paint hold's
+      // settling frame below: mounting can recreate the controls the pre-mount fill populated,
+      // and deferring the re-fill past the hold's rAF leaves a visibly empty window after the
+      // traversal has committed.
+      if (options.pop) {
+        const targetBfcacheId = historyBfcacheId()
+        restoreFormState(targetBfcacheId)
+        if (targetBfcacheId) restoreFormStateWhenMounted(targetBfcacheId, sequence)
+      }
+    }
+  } finally {
+    await releaseNavigationPaintHold(paintHold)
   }
-  // History traversal restores the popped entry's form state over the freshly
-  // mounted tree (browser back/forward form restoration semantics).
+  if (sequence !== navigationSequence) return
+  // Mounting/location subscribers run after the initial pre-mount scroll action.
+  // Reapply traversal coordinates once that work has settled; otherwise a page
+  // effect can reset the restored position to zero after Back.
   if (options.pop) {
-    const targetBfcacheId = historyBfcacheId()
-    restoreFormState(targetBfcacheId)
-    if (targetBfcacheId) restoreFormStateWhenMounted(targetBfcacheId, sequence)
+    await flushClientEffects()
+    scheduleNavigationScroll(url, options)
+  }
+  restoreSwapFocus(focusedBeforeSwap, navigationFocusTarget)
+  // Activity-preserved trees reconcile their keyed leaf against the new entry id
+  // themselves. Replaying the departing DOM snapshot there would resurrect the
+  // old leaf value after React correctly reset it; the fallback is only for the
+  // ordinary remounting path where pnext has replaced layout-owned DOM.
+  if (
+    !preserveInactiveTree &&
+    !options.pop &&
+    departingBfcacheId &&
+    previousPathname !== targetUrl.pathname
+  ) {
+    restoreSharedLayoutFormState(departingBfcacheId, previousPathname, targetUrl.pathname)
   }
   // Same-entry-identity navigation (a search-param nav on the same pathname, a refresh):
   // `key={bfcacheId}` subtrees do NOT remount, so typed values must survive. The commit can
   // still rebuild the page DOM under them (a PPR route streams its page slot in AFTER the
   // swap), so re-apply the departure snapshot as the controls appear - but only to the DOM
   // this swap replaced, never to a control a live island's own render owns (see
-  // islandOwnedControl).
-  else if (departingBfcacheId && departingBfcacheId === historyBfcacheId()) {
+  // islandOwnedControl). The pop equivalent runs inside the commit above, ahead of the paint
+  // hold's settling frame.
+  if (!options.pop && departingBfcacheId && departingBfcacheId === historyBfcacheId()) {
     restoreFormStateWhenMounted(departingBfcacheId, sequence, true)
   }
-
-  // A navigation that only changed parallel slots (same children path AND unchanged search
-  // params - modal patterns) keeps the scroll position. A same-path nav that changes the
-  // search params still scrolls to top.
-  const slotOnlyNav =
-    currentNavState().children === previousChildrenPath &&
-    url.search === previousSearch &&
-    // A nav that changes route params (same children-path template, different segment values
-    // under a shared layout) is NOT slot-only and scrolls to top. True slot-only navs keep the
-    // same route AND params.
-    !remountPageIslands
-  scheduleNavigationScroll(url, { ...options, scroll: slotOnlyNav ? false : options.scroll })
-  if (!url.hash) pruneStylesheets(doc)
-  emitNavigationCommit()
-  emitLocationChange()
 }
 
 function isBotUserAgent() {
@@ -4872,10 +5588,14 @@ const RESTORED_INPUT_TYPES = new Set([
 function formControls(): (HTMLInputElement | HTMLTextAreaElement)[] {
   return [
     ...document.querySelectorAll<HTMLInputElement | HTMLTextAreaElement>('input, textarea'),
-  ].filter(control =>
-    control instanceof HTMLTextAreaElement
-      ? true
-      : RESTORED_INPUT_TYPES.has(control.getAttribute('type')?.toLowerCase() ?? ''),
+  ].filter(
+    control =>
+      // The navigation paint hold is a paint-only CLONE of the departing screen: its copied
+      // controls would shift indices and trip the count guard during the exact window the
+      // synchronous pop restore runs in.
+      !control.closest('[data-pnext-navigation-paint-hold]') &&
+      (control instanceof HTMLTextAreaElement ||
+        RESTORED_INPUT_TYPES.has(control.getAttribute('type')?.toLowerCase() ?? '')),
   )
 }
 
@@ -4949,8 +5669,12 @@ function restoreSharedLayoutFormState(
   const target = targetPathname.split('/').filter(Boolean)
   for (const [index, control] of controls.entries()) {
     if (elementInPageSlot(control)) continue
+    // Only controls rendered by the layout island itself belong to this
+    // shared scope. A nested page island may sit inside that host after it
+    // adopts the page slot, but its bfcacheId intentionally changes on a fresh
+    // push and its keyed form must be allowed to reset.
     const raw = control
-      .closest('pnext-client[data-pnext-layout-segments]')
+      .closest('pnext-client[data-pnext-client]')
       ?.getAttribute('data-pnext-layout-segments')
     if (!raw) continue
     const depth = (JSON.parse(raw) as { depth?: number }).depth
@@ -5095,7 +5819,7 @@ function onLinkIntent(event: Event) {
 // touches roots no earlier pass mounted) and re-sync the router's bookkeeping.
 function onPageShow(event: PageTransitionEvent) {
   if (!event.persisted) return
-  routerState.activeRouteKey = bfRouteKey(location.pathname, location.search)
+  routerState.activeRouteKey = locationKey()
   const entryId = historyState().__pnextEntry
   if (typeof entryId === 'string') routerState.renderedEntryId = entryId
   // A mount claim (mountIslandOnce) left in flight by the freeze can never
@@ -5132,18 +5856,13 @@ export function onPopState() {
   // (what was on screen when the entry was active), not the current
   // document's: from the entry cache when possible, else by re-rendering
   // server-side from the recorded slot state.
-  const cachedPage = entryDocCache.get(entryId)
   const navState = state.__pnextNavState as DocumentNavState | undefined
-  // Broadcast the popped location SYNCHRONOUSLY: softNavigate resolves the
-  // document asynchronously, and a subscriber reading usePathname right after
-  // the traversal would otherwise still see the departing route. The popped
-  // entry's own recorded route state goes with it so useParams stays in step.
-  const poppedRoute = cachedPage ? routeStateFromHtml(cachedPage.html) : undefined
-  if (poppedRoute) window.__PNEXT_ROUTE__ = poppedRoute
-  emitLocationChange()
-  void softNavigate(location.href, { pop: true, navState, cachedPage }).catch(() =>
-    location.reload(),
-  )
+  // Do not broadcast the address-bar change until softNavigate commits the popped document.
+  // Persistent islands belong to the rendered tree, not to the speculative browser location:
+  // publishing here can update their hook state while they are being detached, then make the
+  // post-commit broadcast bail out as unchanged. softNavigate installs the cached document's route
+  // snapshot before mountRoute and emits the location immediately after the navigation commit.
+  void softNavigate(location.href, { pop: true, navState }).catch(() => location.reload())
 }
 
 const eagerLinks = new WeakSet<Element>()
@@ -5153,6 +5872,24 @@ const eagerLinks = new WeakSet<Element>()
 let visibleLinkObserver: IntersectionObserver | undefined
 let visibleLinkObserverDoc: Document | undefined
 
+/** Recompute visible Link prefetches against the newly committed URL/base tree. */
+export function pingVisiblePrefetchLinks() {
+  for (const element of visiblePrefetchElements) {
+    if (!element.isConnected) {
+      visiblePrefetchElements.delete(element)
+      prefetchedElements.delete(element)
+      continue
+    }
+    const href = element.getAttribute('href')
+    if (href) {
+      void prefetchRoute(href, {
+        element,
+        full: isFullPrefetchLink(element),
+      })
+    }
+  }
+}
+
 // `load` links prefetch as soon as they appear; `visible` links when they
 // enter the viewport. Both arrive with the page or with later client renders,
 // so watch the whole document for additions.
@@ -5178,6 +5915,7 @@ function scanEagerPrefetchLinks(root: Element) {
     eagerLinks.add(link)
     if (mode === 'load') {
       const href = link.getAttribute('href')
+      if (isElementVisible(link)) visiblePrefetchElements.add(link)
       if (href) void prefetchRoute(href, { element: link, full: isFullPrefetchLink(link) })
       continue
     }
@@ -5188,6 +5926,7 @@ function scanEagerPrefetchLinks(root: Element) {
     visibleLinkObserver ??= new IntersectionObserver(entries => {
       for (const entry of entries) {
         if (!entry.isIntersecting) {
+          visiblePrefetchElements.delete(entry.target)
           // The link left the viewport (scrolled/hidden) — cancel its pending
           // prefetch task: queued work is dropped, an in-flight task stops
           // before its next phase, and the pending cache entry is evicted so
@@ -5196,6 +5935,7 @@ function scanEagerPrefetchLinks(root: Element) {
           if (task) cancelPrefetchTask(task)
           continue
         }
+        visiblePrefetchElements.add(entry.target)
         const href = entry.target.getAttribute('href')
         if (href)
           void prefetchRoute(href, {
@@ -5206,6 +5946,7 @@ function scanEagerPrefetchLinks(root: Element) {
     })
     visibleLinkObserver.observe(link)
     if (isElementVisible(link)) {
+      visiblePrefetchElements.add(link)
       const href = link.getAttribute('href')
       if (href) void prefetchRoute(href, { element: link, full: isFullPrefetchLink(link) })
       continue
@@ -5245,16 +5986,46 @@ export function installRouterFull() {
   // Seed the hard-loaded entry's ids BEFORE any island mounts — the hub already
   // did that (see ./index.ts installRouter); this tier picks up from there.
   storeNavState()
-  // A streaming route is still showing its shell when the async entry module first runs - the
-  // deferred `<template data-pnext-stream>` chunks have not been grafted in yet. Snapshotting
-  // `outerHTML` now would cache the LOADING SHELL as the resolved document, so a later
-  // navigation back commits that stale shell. Defer the snapshot+seed until load completes.
+  // Next's initial RSC payload seeds the segment cache before request params resolve. PNext's hard
+  // HTML load carries only the resolved continuation, so obtain the prerendered current-route stage
+  // now and keep it as the cacheComponents segment seed. Default apps do no extra work.
+  if (activityBfcacheEnabled()) void prefetchRoute(location.href, { currentUrl: true })
+  // Bind every delayed hard-load operation to the document and history entry that installed this
+  // runtime. `load` can fire after a fast soft navigation has already committed; consulting the
+  // then-current location/state would file the original source under the destination entry key.
+  const hardLoadRouteKey = locationKey()
+  const hardLoadPathname = location.pathname
+  let hardLoadHtml =
+    (window as { __PNEXT_SHELL_HTML__?: string }).__PNEXT_SHELL_HTML__ ||
+    `<!doctype html>${document.documentElement.outerHTML}`
+  // The shell bootstrap can run before these settled, URL-specific scripts parse. A traversal must
+  // restore them with the immutable entry source; otherwise a whole-page client component remounts
+  // against the route/props globals of the page just left (for example Back to `[id]=1` renders 2).
+  if (currentNavState().children !== hardLoadPathname)
+    hardLoadHtml += document.getElementById('__PNEXT_NAV_STATE__')?.outerHTML ?? ''
+  const hardLoadEntrySrc = entryScriptSrc(document)
+  if (hardLoadEntrySrc) hardLoadHtml += `<script type="module" src="${hardLoadEntrySrc}"></script>`
+  const hardLoadRestoreSource: PrefetchedPage = {
+    html: hardLoadHtml,
+    finalUrl: location.href,
+    ok: true,
+    p: (window as typeof window & { __PNEXT_PROPS__?: unknown }).__PNEXT_PROPS__,
+  }
+  const hardLoadStaticStage = documentStaticHintFromHtml(hardLoadRestoreSource.html)?.isStatic
+    ? undefined
+    : preHydrationShell()
+  // Entry-document identity is needed as soon as navigation can start, not at window.load.
+  cacheEntryDocument(hardLoadRestoreSource)
+  const hardLoadEntryId = historyState().__pnextEntry
+  // The source snapshot is already entry-bound above. Defer only navigation-cache seeding until
+  // load, when the original response has completed its browser lifecycle.
   const captureHardLoad = () => {
-    const hardLoadedPage: PrefetchedPage = {
-      html: `<!doctype html>${document.documentElement.outerHTML}`,
-      finalUrl: location.href,
-      ok: true,
-    }
+    // A fast navigation can commit before the original window load event. The live DOM then belongs
+    // to another entry and must not be filed as this hard load's settled segment payload.
+    if (historyState().__pnextEntry !== hardLoadEntryId) return
+    const settledHtml = `<!doctype html>${document.documentElement.outerHTML}`
+    const hardLoadHint = documentStaticHintFromHtml(settledHtml)
+    const hardLoadRuntimePrefetch = htmlRuntimePrefetch(settledHtml)
     // A hard HTML load carries no `x-nextjs-stale-time` response header, so
     // seedNavigationEntry would fall to the dynamic default (0) and a fully
     // static page gets re-requested on the next navigation. The document inlines
@@ -5262,31 +6033,46 @@ export function installRouterFull() {
     // when the route is static, seed the TRUE static window (its own `cacheLife`
     // stale seconds, or the configured static default) and mark it prerendered so
     // no `_rsc` refetch fires while the window is fresh.
-    const hint = documentStaticHint()
-    if (hint?.isStatic) {
-      hardLoadedPage.staleTimeSeconds = hint.staleTime ?? shellStaleTimeMs() / 1000
-      hardLoadedPage.segmentPrerendered = true
+    const navigationSeedPage: PrefetchedPage = {
+      ...hardLoadRestoreSource,
+      html: settledHtml,
+    }
+    if (hardLoadHint?.isStatic) {
+      navigationSeedPage.staleTimeSeconds = hardLoadHint.staleTime ?? shellStaleTimeMs() / 1000
+      navigationSeedPage.segmentPrerendered = true
     }
-    cacheEntryDocument(hardLoadedPage)
+    // Keep the entry-bound history document as immutable server source: ordinary
+    // (non-cacheComponents) traversals must remount it, rather than restoring a
+    // hydrated tree whose effect cleanup may already have mutated application
+    // state. The navigation-data seed has a different contract. Once the hard
+    // load settles, its resolved page data is fresh for staleTimes.dynamic and a
+    // later Link back to this URL must be able to reuse it.
     // Visited-page seeding: the hard load is as fresh as a fetch — an immediate
     // soft navigation back to this URL within the dynamic window reuses it.
     seedNavigationEntry(
-      location.pathname + location.search,
-      location.pathname,
-      hardLoadedPage,
+      hardLoadRouteKey,
+      hardLoadPathname,
+      navigationSeedPage,
       undefined,
       // A streaming document's static stage is unrecoverable from the settled
       // DOM; the pre-promotion stash is the only faithful copy.
-      hint?.isStatic ? undefined : preHydrationShell(),
+      hardLoadStaticStage,
       true,
     )
-    storeBfDoc(location.pathname + location.search, hardLoadedPage)
+    storeBfDoc(hardLoadRouteKey, navigationSeedPage)
+    // A STREAMING route's pre-promotion shell always carries a pending hole, so the pop guard
+    // in softNavigate rejects it and every traversal back to this entry refetches. The settled
+    // DOM is this entry's only complete render — re-file it so history restoration stays
+    // network-free. Complete (non-streaming) sources keep their immutable pre-hydration copy.
+    if (streamHasPendingHole(hardLoadRestoreSource.html) && !streamHasPendingHole(settledHtml)) {
+      cacheEntryDocument(navigationSeedPage)
+    }
     // `prefetch = 'allow-runtime'`: the document that just loaded shows RESOLVED sampled
     // content, but its cacheable stage is the runtime-prefetch shell, which the hard load never
     // fetched. Ask the server for that payload so a later navigation back paints the sampled
     // content instead of the Suspense fallbacks.
-    if (documentRuntimePrefetch()) {
-      void prefetchRoute(location.href, { full: true, currentUrl: true })
+    if (hardLoadRuntimePrefetch) {
+      void prefetchRoute(hardLoadRestoreSource.finalUrl, { full: true, currentUrl: true })
     }
   }
   if (document.readyState === 'complete') captureHardLoad()