@wular/pnext 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A fast little framework for server-first React apps, fully compatible with Next.js",
   "type": "module",
   "bin": {

package/reference/navigation.md

@@ -45,11 +45,11 @@ Prefetch warms the target page and its assets. Set the mode per link with the `p
 
 The app-wide default can be set with the `prefetch` field in `pnext.config.ts`, described in [Config](./config.md).
 
-Requests use low network priority. At most four run at once, though the hover-intent lane allows up to twelve. The core fallback expiry is five minutes. Prefetch does nothing in development.
+Requests use low network priority. At most four run at once, though the hover-intent lane allows up to twelve. The core fallback expiry is five minutes. Development prefetches like production, except under `compat.next`, which follows Next and does not prefetch in development.
 
 ## Soft navigation
 
-Link clicks and router pushes swap the page in place instead of reloading the document, so shared chunks and CSS are never re-downloaded. Back and forward stay soft and restore scroll. Cross-origin targets, non-HTML responses, and fetch failures fall back to a full page load.
+Link clicks and router pushes swap the page in place instead of reloading the document, so shared chunks and CSS are never re-downloaded. A new page starts at the top, and back and forward stay soft and restore scroll. When a link shows a dynamic page again from the router cache, the page refreshes in the background and the fresh render replaces it in place. Cross-origin targets, non-HTML responses, and fetch failures fall back to a full page load.
 
 ## Redirects and not found
 

package/src/cli/adapters/vercel.ts

@@ -14,6 +14,7 @@ import { resolveImport, workspacePackageRoots } from '../../resolve/imports'
 import { findProxyFile, proxyRoutePatterns, type ProxyModule } from '../../routing/proxy'
 import { cacheRoot } from '../boot/named-bin'
 import { startWarmChild, type WarmChild } from './vercel-warm'
+import { escapeRegex } from '../../utils/code'
 import { listFiles, toPosixPath, writeText } from '../../utils/fs'
 import { createVerboseLogger, type VerboseLogger } from '../../utils/verbose'
 import type { BuildManifest, StaticFileMetadata } from '../../types'
@@ -149,7 +150,13 @@ function shipsFile(pack: PackRules, name: string) {
 interface VercelConfig {
   version: 3
   routes?: (
-    | { src: string; dest?: string; headers?: Record<string, string>; continue?: boolean }
+    | {
+        src: string
+        dest?: string
+        methods?: string[]
+        headers?: Record<string, string>
+        continue?: boolean
+      }
     | { handle: 'filesystem' }
   )[]
   overrides?: Record<string, { path?: string; contentType?: string }>
@@ -205,15 +212,12 @@ export async function writeVercelOutput(
     // CDN serves those bytes itself - without it every stylesheet and chunk fell through to the
     // server function: served, but at function cost with no edge cache.
     ...compatStaticRewrite(config, outputPath),
-    // Chunk and font filenames are content-hashed; serve them immutable.
-    {
-      src: '^/assets/(chunks|fonts)/.*',
-      headers: { 'cache-control': 'public, max-age=31536000, immutable' },
-      continue: true,
-    },
+    // Every content-hashed build asset, exactly the set `pnext start` serves immutable.
+    await immutableAssetRoute(),
     // Proxy-matched paths go to the server function before the CDN filesystem
     // check — `pnext start` runs the proxy ahead of static files too.
     ...(await proxyRoutes(config)),
+    ...staticHeaderRoutes(staticFiles),
     { handle: 'filesystem' },
     { src: '^/.*$', dest: `/${SERVER_FUNCTION}` },
   ]
@@ -1375,9 +1379,83 @@ async function staticOverrides(
   return overrides
 }
 
+async function immutableAssetRoute() {
+  const { immutableAssetPrefixes, immutableCacheControl } = await import('../serve/pipeline')
+  const prefixes = [...new Set(immutableAssetPrefixes())].map(escapeRegex)
+  return {
+    src: `^/(?:${prefixes.join('|')})`,
+    headers: { 'cache-control': immutableCacheControl },
+    continue: true,
+  }
+}
+
+// Headers a CDN route cannot replay; a file that sets one stays on the server function.
+const functionOnlyHeaders = new Set([
+  'content-length',
+  'content-encoding',
+  'transfer-encoding',
+  'connection',
+  'set-cookie',
+])
+
 function canServeStaticOnVercel(metadata: StaticFileMetadata) {
+  if (metadata.status !== 200) return false
+  const headers = routeHeaders(metadata)
+  if (headers.length === 0) return true
+  // ISR state needs the function to revalidate.
   return (
-    metadata.status === 200 &&
-    metadata.headers.every(([name]) => name.toLowerCase() === 'content-type')
+    metadata.revalidateSeconds === undefined &&
+    metadata.expireSeconds === undefined &&
+    !metadata.tags?.length &&
+    headers.every(([name]) => !functionOnlyHeaders.has(name.toLowerCase()))
   )
 }
+
+/** Headers beyond content-type, which an override carries instead. */
+function routeHeaders(metadata: StaticFileMetadata) {
+  return metadata.headers.filter(([name]) => name.toLowerCase() !== 'content-type')
+}
+
+// Keeps each route pattern well inside Vercel's route size limits.
+const maxRouteSourceLength = 2000
+
+/**
+ * Route headers for the CDN-served static files whose headers an override cannot carry, so the CDN
+ * answers with what `pnext start` sends. Files sharing a header set share a route.
+ */
+function staticHeaderRoutes(staticFiles: Record<string, StaticFileMetadata>) {
+  const groups = new Map<string, { headers: Record<string, string>; patterns: string[] }>()
+  for (const [relative, metadata] of Object.entries(staticFiles)) {
+    const extra = routeHeaders(metadata)
+    if (extra.length === 0 || !canServeStaticOnVercel(metadata)) continue
+    const headers = Object.fromEntries(new Headers(extra))
+    const key = JSON.stringify(headers)
+    const group = groups.get(key) ?? { headers, patterns: [] }
+    groups.set(key, group)
+    group.patterns.push(servedPathPattern(relative))
+  }
+  return [...groups.values()].flatMap(({ headers, patterns }) => {
+    const sources: string[] = []
+    for (const pattern of patterns) {
+      const last = sources.length - 1
+      if (last >= 0 && sources[last]!.length + pattern.length < maxRouteSourceLength) {
+        sources[last] += `|${pattern}`
+      } else {
+        sources.push(pattern)
+      }
+    }
+    return sources.map(source => ({
+      src: `^/(?:${source})$`,
+      methods: ['GET', 'HEAD'],
+      headers,
+      continue: true,
+    }))
+  })
+}
+
+/** A static file's request paths: `a/index.html` also answers `/a` and `/a/`. */
+function servedPathPattern(relative: string) {
+  if (relative === 'index.html') return '(?:index\\.html)?'
+  if (!relative.endsWith('/index.html')) return escapeRegex(relative)
+  return `${escapeRegex(relative.slice(0, -'/index.html'.length))}(?:/|/index\\.html)?`
+}

package/src/cli/serve/pipeline.ts

@@ -1352,10 +1352,18 @@ export const immutableCacheControl = 'public, max-age=31536000, immutable'
  * and stay revalidating; the public/ tree the app ships is likewise untouched.
  */
 export function immutableAssetPath(relativePath: string) {
-  if (relativePath.startsWith('assets/') || relativePath.startsWith('_next/static/')) return true
-  return getAssetExtensions()
-    .staticAssetPublicPrefixes()
-    .some(prefix => relativePath.startsWith(prefix.replace(/^\/+/, '')))
+  return immutableAssetPrefixes().some(prefix => relativePath.startsWith(prefix))
+}
+
+/** The public-relative prefixes `immutableAssetPath` covers. */
+export function immutableAssetPrefixes() {
+  return [
+    'assets/',
+    '_next/static/',
+    ...getAssetExtensions()
+      .staticAssetPublicPrefixes()
+      .map(prefix => prefix.replace(/^\/+/, '')),
+  ]
 }
 
 async function firstFile(root: string, files: string[]) {

package/src/client/router/runtime.ts

@@ -20,6 +20,7 @@ import {
 import {
   exportDocumentFetcher,
   loadingShellPredictionPolicy,
+  prefetchStaleTimePolicy,
   prefetchStaleTimeMs,
   revalidationPrefetchDelayMs,
   segmentCachePolicy,
@@ -30,7 +31,9 @@ import {
   emitLocationChange,
   emitNavigationCommit,
   emitNavigationStart,
+  navigationScrollAction,
   scheduleNavigationScroll,
+  setNavigationScrollAction,
   withSilentLocationChange,
 } from './events'
 import type {
@@ -39,6 +42,7 @@ import type {
   EntryModule,
   LinkPrefetchMode,
   LoadingShellPrediction,
+  NavigationScrollAction,
   PrefetchedPage,
   PrefetchOptions,
   SegmentCacheHit,
@@ -57,14 +61,17 @@ export interface BrowserRouteState {
   runtimePrefetch?: boolean
 }
 
+const ROUTE_STATE_PREFIX = 'window.__PNEXT_ROUTE__='
+
 function documentRouteState(doc: Document): BrowserRouteState | undefined {
-  const prefix = 'window.__PNEXT_ROUTE__='
   const source = [...doc.scripts]
     .map(script => script.textContent ?? '')
-    .find(text => text.startsWith(prefix))
+    .find(text => text.startsWith(ROUTE_STATE_PREFIX))
   if (!source) return undefined
   try {
-    return JSON.parse(source.slice(prefix.length).replace(/;\s*$/, '')) as BrowserRouteState
+    return JSON.parse(
+      source.slice(ROUTE_STATE_PREFIX.length).replace(/;\s*$/, ''),
+    ) as BrowserRouteState
   } catch {
     return undefined
   }
@@ -320,6 +327,8 @@ function materializeStreamedSegments(doc: Document) {
   for (const chunk of doc.querySelectorAll<HTMLElement>(
     'div[hidden][data-pnext-stream], template[data-pnext-stream]',
   )) {
+    // Its promotion script has nothing left to do, and re-running it would only trip a script CSP.
+    if (chunk.nextElementSibling?.tagName === 'SCRIPT') chunk.nextElementSibling.remove()
     const id = chunk.getAttribute('data-pnext-stream')
     const suspense = id
       ? doc.querySelector(`pnext-suspense[data-pnext-suspense="${CSS.escape(id)}"]`)
@@ -1053,6 +1062,11 @@ function swapBody(
         continue
       }
       if (node.hasAttribute('data-pnext-dev')) continue
+      // Callers install the route state from the document; re-running it only trips a script CSP.
+      if (node.text.startsWith(ROUTE_STATE_PREFIX)) {
+        fragment.append(document.importNode(node, true))
+        continue
+      }
       // Parser-created scripts are inert; rebuild them so props, route
       // state, and streamed-chunk patches execute in document order when the
       // fragment lands in the live document.
@@ -1092,7 +1106,7 @@ function swapBody(
       cursor = next
     }
   }
-  if (paintHold) document.body.append(paintHold)
+  if (paintHold) placeNavigationPaintHold(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)
@@ -1102,6 +1116,12 @@ function swapBody(
 /** Keep the last complete screen painted while client roots mount into the committed document. */
 type NavigationPaintHold = HTMLElement & {
   __pnextObserver?: MutationObserver
+  /** The window scroll when the copy was taken. */
+  __pnextScroll?: [number, number]
+  /** The `[data-scroll-root]` scroll the copy shows. */
+  __pnextScrollTop?: number
+  /** The navigation that removes the hold. */
+  __pnextSequence?: number
 }
 
 function removeNavigationPaintHold(hold: NavigationPaintHold) {
@@ -1109,14 +1129,19 @@ function removeNavigationPaintHold(hold: NavigationPaintHold) {
   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)
+// A released hold until a frame renders without it: until then it is still what the screen shows.
+let releasedHold: NavigationPaintHold | null = null
+
+function createNavigationPaintHold(sequence: number): NavigationPaintHold | null {
+  // A prior hold on screen is taken over, so the older release is a no-op.
+  const priorHold =
+    document.querySelector<NavigationPaintHold>('[data-pnext-navigation-paint-hold]') ??
+    releasedHold
+  releasedHold = null
+  if (priorHold) {
+    priorHold.__pnextSequence = sequence
+    return priorHold
+  }
   const roots = [...document.body.children].filter(
     element =>
       !element.hasAttribute('data-pnext-navigation-paint-hold') &&
@@ -1124,12 +1149,20 @@ function createNavigationPaintHold(): NavigationPaintHold | null {
       element.textContent?.trim(),
   )
   if (roots.length === 0) return null
-  const hold = document.createElement('div')
+  const hold: NavigationPaintHold = 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)))
+  // compat.next keeps 0.1.0's unscrolled copy, which its server action refresh scroll relies on.
+  if (typeof __PNEXT_NEXT_ROUTER__ === 'undefined')
+    hold.__pnextScroll = [window.scrollX, window.scrollY]
+  hold.__pnextSequence = sequence
+  // A <body> shell over the whole hold: body styles lay out and paint the copy as the page was.
+  const body = document.body.cloneNode() as HTMLElement
+  body.style.minHeight = '100%'
+  body.append(...roots.map(root => root.cloneNode(true)))
+  hold.append(body)
   // 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')
@@ -1159,19 +1192,27 @@ function attachNavigationPaintHold(
   // 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)
+  placeNavigationPaintHold(hold)
+  // A newer navigation leaves the hold up: its commit takes it over, or this release removes it.
   hold.__pnextObserver ??= new MutationObserver(() => {
-    if (sequence !== navigationSequence) {
-      return removeNavigationPaintHold(hold)
-    }
-    if (!hold.isConnected) document.body.append(hold)
+    if (!hold.isConnected) placeNavigationPaintHold(hold)
   })
   hold.__pnextObserver.observe(document.documentElement, { childList: true, subtree: true })
   const scrollRoot = hold.querySelector<HTMLElement>('[data-scroll-root]')
-  if (scrollRoot) scrollRoot.scrollTop = scrollTop
+  if (scrollRoot) scrollRoot.scrollTop = hold.__pnextScrollTop ??= scrollTop
+}
+
+/** Append the hold scrolled as the departing page was; appending resets an element's scroll. */
+function placeNavigationPaintHold(hold: NavigationPaintHold) {
+  document.body.append(hold)
+  if (hold.__pnextScroll) hold.scrollTo?.(...hold.__pnextScroll)
 }
 
-async function releaseNavigationPaintHold(hold: NavigationPaintHold | null) {
+async function releaseNavigationPaintHold(
+  hold: NavigationPaintHold | null,
+  sequence: number,
+  reveal?: () => void,
+) {
   if (!hold) return
   // mountRoute, client effects and the navigation commit have completed before
   // this runs. Keep the departing frame through the next rendering opportunity,
@@ -1179,7 +1220,17 @@ async function releaseNavigationPaintHold(hold: NavigationPaintHold | null) {
   if (window.requestAnimationFrame) {
     await new Promise<void>(resolve => window.requestAnimationFrame(() => resolve()))
   }
+  if (hold.__pnextSequence !== sequence) return
+  reveal?.()
   removeNavigationPaintHold(hold)
+  if (!window.ResizeObserver) return
+  releasedHold = hold
+  // Observing fires at the next rendering update, the first frame that paints without the hold.
+  const rendered = new ResizeObserver(() => {
+    rendered.disconnect()
+    if (releasedHold === hold) releasedHold = null
+  })
+  rendered.observe(document.documentElement)
 }
 
 /**
@@ -1510,6 +1561,11 @@ function isDevDocument() {
   return Boolean(document.querySelector('script[data-pnext-dev]'))
 }
 
+// Next's dev router neither prefetches nor paints loading states; core dev navigates like production.
+function nextDevDocument() {
+  return prefetchStaleTimePolicy !== undefined && isDevDocument()
+}
+
 // `replace` is also set for history TRAVERSALS (options.pop): assign() would
 // push a new entry over the popped one and truncate the forward stack, so a
 // bailout during back/forward must replace the current entry instead.
@@ -1541,6 +1597,27 @@ function saveScrollPosition() {
   }
 }
 
+// Defined by compat.next builds, whose router policies replace core's scroll and refresh ones.
+declare const __PNEXT_NEXT_ROUTER__: boolean | undefined
+
+// Core's scroll policy when compat installs none: a new page starts at the top, a traversal
+// returns to where its entry was left.
+const coreNavigationScroll: NavigationScrollAction = (url, { pop, scroll }) => {
+  const state = historyState()
+  const saved = pop
+    ? (entryScroll.get(state.__pnextEntry) ?? (state.__pnextScroll as number[] | undefined))
+    : undefined
+  const [x = 0, y = 0] = saved ?? []
+  // A traversal to an entry with no saved position lands on its hash, as a new visit does.
+  const target =
+    !saved && url.hash && document.getElementById(decodeURIComponent(url.hash.slice(1)))
+  if (target) target.scrollIntoView()
+  else if (pop || scroll !== false) window.scrollTo(x, y)
+}
+
+// Where each entry was left, pops included, which cannot write the state of the entry they leave.
+const entryScroll = new Map<unknown, number[]>()
+
 function storeNavState() {
   try {
     history.replaceState(
@@ -2266,6 +2343,8 @@ export function rearmVisiblePrefetches(): void {
   const retry = () => {
     if (generation !== revalidationPrefetchGeneration) return
     revalidationPrefetchBlocked = false
+    // A test host may tear the window down before the timer fires.
+    if (typeof window === 'undefined') return
     for (const element of prefetchedElements) {
       if (!element.isConnected) {
         prefetchedElements.delete(element)
@@ -2516,6 +2595,8 @@ export interface PrefetchEntry {
   stateKey: string
   /** A pending prefetch always dedupes; settled stale data must refetch. */
   settled: boolean
+  /** When the response landed, for entries that started as a pending prefetch. */
+  settledTime?: number
   /** Byte size of the settled document (LRU size accounting). */
   bytes?: number
   /** Settled as a shell-only (partial prefetch) response — see PrefetchedPage. */
@@ -2855,9 +2936,7 @@ export function prefetchRoute(
   href: string,
   options: PrefetchOptions = {},
 ): Promise<PrefetchedPage | null> {
-  // Dev pages render per request and entries build on demand; hover prefetch
-  // would hammer the dev server for little gain. Navigation still fetches.
-  if (isDevDocument()) return Promise.resolve(null)
+  if (nextDevDocument()) return Promise.resolve(null)
   if (isBotUserAgent()) return Promise.resolve(null)
   // `strict` is handled at the facade, the only entry point that can be handed
   // an unparseable href; everything reaching here already resolved once.
@@ -3065,8 +3144,10 @@ export function prefetchRoute(
       // Null = task stopped short with no data; a settled null would dedupe
       // every later reveal into null, so drop the entry and let a viewport
       // re-entry reschedule.
-      if (fetched) entry.settled = true
-      else prefetchCache.delete(cacheKey)
+      if (fetched) {
+        entry.settled = true
+        entry.settledTime = clientClockNow()
+      } else prefetchCache.delete(cacheKey)
     }
     // Size accounting only applies to settled documents — re-trim now that
     // this entry's bytes count against the budget.
@@ -3997,7 +4078,6 @@ export function showLoadingShell(
 ) {
   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)
   // A STATIC STAGE owns whatever chunks streamed with it, so resolve them before picking what
@@ -4035,6 +4115,10 @@ export function showLoadingShell(
   if (!markerRange && slotContainer === document.body && !scopedOwner) return false
   const container = scopedOwner ?? slotContainer
   const fragment = document.createDocumentFragment()
+  // A live page slot is filled from the incoming page slot, never from a container inside it.
+  // compat.next keeps its own fill, which its nested parallel-slot layouts rely on.
+  const incomingSlot =
+    typeof __PNEXT_NEXT_ROUTER__ === 'undefined' && markerRange ? pageSlotRange(doc.body) : null
   // 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
   // with only the suspense children loses the eagerly prefetched layout.
@@ -4043,17 +4127,19 @@ export function showLoadingShell(
     (container.id ? doc.getElementById(container.id) : null) ??
     doc.querySelector('[data-pnext-root]') ??
     (container === document.body ? doc.body : null)
-  const sourceNodes = incomingTarget
-    ? [...incomingTarget.childNodes]
-    : inline
-      ? // The inline anchor is whatever element holds the markers (often <body>);
-        // only the fallback BETWEEN them is this boundary's content.
-        inline.nodes
-      : suspense
-        ? [...(suspense.closest('pnext-layout[data-pnext-segment]') ?? suspense).childNodes]
-        : // Boundary-free markup with no page container to copy from: there is
-          // nothing this paint could put on screen.
-          null
+  const sourceNodes = incomingSlot
+    ? incomingSlot[2]
+    : incomingTarget
+      ? [...incomingTarget.childNodes]
+      : inline
+        ? // The inline anchor is whatever element holds the markers (often <body>);
+          // only the fallback BETWEEN them is this boundary's content.
+          inline.nodes
+        : suspense
+          ? [...(suspense.closest('pnext-layout[data-pnext-segment]') ?? suspense).childNodes]
+          : // Boundary-free markup with no page container to copy from: there is
+            // 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
@@ -4085,7 +4171,6 @@ export 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
 }
 
@@ -4263,7 +4348,6 @@ 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
@@ -4297,7 +4381,6 @@ 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
 }
 
@@ -4425,6 +4508,10 @@ function unsettledPrefetchDeadline(): Promise<null> {
   return new Promise(resolve => setTimeout(() => resolve(null), UNSETTLED_PREFETCH_WAIT_MS))
 }
 
+// Kept copies older than REVALIDATE_AFTER_MS that core commits, then swaps for their fresh render.
+const keptCopies = new WeakMap<PrefetchedPage, Promise<PrefetchedPage | null>>()
+const REVALIDATE_AFTER_MS = 2_000
+
 async function pageForNavigation(
   url: URL,
   options: SoftNavigateOptions = {},
@@ -4491,7 +4578,18 @@ async function pageForNavigation(
       cached.settled || cached.full
         ? await cached.page
         : await Promise.race([cached.page, unsettledPrefetchDeadline()])
-    if (page && !page.shellOnly) return page
+    if (page && !page.shellOnly) {
+      if (
+        typeof __PNEXT_NEXT_ROUTER__ === 'undefined' &&
+        !prefetchStaleTimePolicy &&
+        now - (cached.settledTime ?? cached.time) > REVALIDATE_AFTER_MS &&
+        !documentStaticHintFromHtml(page.html)?.isStatic
+      ) {
+        const fresh = fetchPage(url.href, { fullRender: true }).catch(() => null)
+        keptCopies.set(page, fresh)
+      }
+      return page
+    }
     // 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.
@@ -4988,6 +5086,8 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // into the live body. Capturing later would save the target's fallback as
   // the previous history entry and restore a permanently stuck "Loading...".
   if (!options.pop) saveScrollPosition()
+  if (typeof __PNEXT_NEXT_ROUTER__ === 'undefined')
+    entryScroll.set(routerState.renderedEntryId, [window.scrollX, window.scrollY])
   if (departingBfcacheId) saveFormState(departingBfcacheId)
   // Snapshot the departing page's live island roots NOW, before a loading shell
   // can paint over (and detach) them below — they are stashed for back/forward
@@ -4996,11 +5096,6 @@ 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
@@ -5056,19 +5151,14 @@ 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 devSoftNavigation = nextDevDocument()
   const onShell =
     restorePage || options.pop || refreshLike
       ? undefined
       : (shellHtml: string) => {
           if (cachedStagePainted) 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
+          if (!showLoadingShell(shellHtml, sequence, url, undefined, false, true)) return
           // A loading boundary is a committed navigation state.
           pushOptimisticUrl()
           scheduleNavigationScroll(url, options)
@@ -5396,12 +5486,17 @@ 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)
+  // Copy the screen as it is now, a loading or static stage included, before anything unmounts.
+  // The resolved client-root commit shows this copy only while its first complete paint settles.
+  const paintHoldScrollTop =
+    document.querySelector<HTMLElement>('[data-scroll-root]')?.scrollTop ?? 0
+  const paintHold = createNavigationPaintHold(sequence)
   let focusedBeforeSwap: Element | null = null
   let navigationFocusTarget: HTMLElement | null = null
   try {
+    // 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)
     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.
@@ -5465,7 +5560,8 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
     // 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)
+    // Core keeps the departing sheets while the paint hold still shows the departing screen.
+    if (!url.hash && (stylesheetReconciler || !paintHold)) 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.
@@ -5514,7 +5610,10 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
       }
     }
   } finally {
-    await releaseNavigationPaintHold(paintHold)
+    await releaseNavigationPaintHold(paintHold, sequence, () => {
+      if (!url.hash && !stylesheetReconciler && sequence === navigationSequence)
+        pruneStylesheets(doc)
+    })
   }
   if (sequence !== navigationSequence) return
   // Mounting/location subscribers run after the initial pre-mount scroll action.
@@ -5547,6 +5646,19 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   if (!options.pop && departingBfcacheId && departingBfcacheId === historyBfcacheId()) {
     restoreFormStateWhenMounted(departingBfcacheId, sequence, true)
   }
+  if (typeof __PNEXT_NEXT_ROUTER__ === 'undefined' && keptCopies.has(page))
+    void revalidateCommittedPage(targetUrl, sequence, page)
+}
+
+async function revalidateCommittedPage(url: URL, sequence: number, page: PrefetchedPage) {
+  const fresh = await keptCopies.get(page)
+  if (!fresh?.ok || fresh.html === page.html || sequence !== navigationSequence) return
+  await softNavigate(url.href, {
+    replace: true,
+    scroll: false,
+    refreshLike: true,
+    cachedPage: fresh,
+  })
 }
 
 function isBotUserAgent() {
@@ -6103,5 +6215,7 @@ export function installRouterFull() {
   )
   window.addEventListener('popstate', onPopState)
   window.addEventListener('pageshow', onPageShow)
+  if (typeof __PNEXT_NEXT_ROUTER__ === 'undefined' && !navigationScrollAction)
+    setNavigationScrollAction(coreNavigationScroll)
   watchEagerPrefetchLinks()
 }

package/src/compat/client/errors/install.ts

@@ -222,6 +222,8 @@ function installStreamErrorBoundaries(
   const observe = () => {
     scan(document)
     new MutationObserver(mutations => {
+      // A test host may tear the DOM globals down before a queued record is delivered.
+      if (typeof Element === 'undefined') return
       for (const mutation of mutations) {
         for (const node of Array.from(mutation.addedNodes)) {
           if (!(node instanceof Element)) continue

package/src/compat/register/bundler.ts

@@ -387,6 +387,8 @@ export function registerBundlerExtensions(config: ResolvedConfig): void {
       // the defaults + resolver from every client bundle.
       __PNEXT_IMAGE_CONFIG_INLINE__: JSON.stringify(getImagesConfig()),
       __PNEXT_IMAGE_CONFIG_INLINED__: 'true',
+      // Next's router policies replace core's scroll and refresh ones, so client bundles drop those.
+      ...(nextCompatEnabled(config) ? { __PNEXT_NEXT_ROUTER__: 'true' } : {}),
       // publicRuntimeConfig inlined the same way; omitted entirely when unset so an app that
       // never configures it adds zero bytes (unlike images, there is no default to drop).
       ...(Object.keys(publicRuntimeConfig()).length > 0

package/src/render/renderer.ts

@@ -7001,7 +7001,11 @@ function unwrapUnusedPageSlot(html: string, mode: PageSlotMarkerMode): string {
     return html.replace(/<!--pnext-page:[^>]*-->/, '<!--pnext-page:-->')
   }
   const slot = pageSlotSpan(html)
-  return slot ? html.slice(0, slot.start) + slot.children + html.slice(slot.end) : html
+  if (!slot) return html
+  // `keep` leaves the empty anchors a soft navigation grafts a kept layout's next page between.
+  const children =
+    mode === 'keep' ? `<!--pnext-page:-->${slot.children}<!--/pnext-page-->` : slot.children
+  return html.slice(0, slot.start) + children + html.slice(slot.end)
 }
 
 function serializeNeutralClientIslands(html: string) {

package/src/runtime/modules.ts

@@ -1440,6 +1440,7 @@ async function writeCompiledFile(file: string, contents: string) {
 function missingCompiledArtifact(entry: string): string | undefined {
   const root = compiledArtifactProfileRoot(entry)
   if (!root) return existsSync(entry) ? undefined : entry
+  const serverRoot = path.dirname(root)
 
   const visiting = new Set<string>()
   const visit = (file: string): string | undefined => {
@@ -1447,7 +1448,7 @@ function missingCompiledArtifact(entry: string): string | undefined {
     if (!existsSync(file)) return file
     // Raw framework/package file URLs are ordinary immutable dependencies, not
     // members of the materialized graph whose publication order we own.
-    if (!isInside(root, file) || !compiledScriptFilePattern.test(file)) return undefined
+    if (!isInside(serverRoot, file) || !compiledScriptFilePattern.test(file)) return undefined
 
     visiting.add(file)
     const cachedTargets = completeArtifactClosures.get(file)
@@ -1480,13 +1481,13 @@ function missingCompiledArtifact(entry: string): string | undefined {
       } catch {
         return sourcePath
       }
-      if (!isInside(root, target)) {
+      const emittedRoot = compiledArtifactProfileRoot(target)
+      if (!emittedRoot) continue
+      // Profiles share one closure: a 'use client' module compiles its imports into the client profile.
+      if (!isInside(serverRoot, target)) {
         if (existsSync(target)) continue
-        const emittedRoot = compiledArtifactProfileRoot(target)
-        // A different profile is produced by a separate build phase. Only a
-        // dead reference to this same profile can be a relocated cache member.
-        if (!emittedRoot || path.basename(emittedRoot) !== path.basename(root)) continue
-        target = path.resolve(root, path.relative(emittedRoot, target))
+        // A dead reference into another cache is a relocated member of this one.
+        target = path.resolve(serverRoot, path.relative(path.dirname(emittedRoot), target))
       }
       const missing = visit(target)
       if (missing) return missing