@wular/pnext 0.1.1 → 0.1.3

package/package.json

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

package/reference/navigation.md

@@ -49,7 +49,7 @@ Requests use low network priority. At most four run at once, though the hover-in
 
 ## 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. 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.
+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. A dynamic page the router kept from a prefetch or a visit is reused as-is for 5 seconds. After that, the link paints the page's layout and loading fallbacks at once and streams fresh data in, so old data never shows; the frame stays reusable for five minutes. Back and forward restore the page as it was shown. 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

@@ -129,8 +129,10 @@ export function isRewriteDocument(html: string, pathname: string): boolean {
   return !routePatternMatchesPathname(state.route, pathname, state.catchAllOptional)
 }
 
-export function routeParamBoundaryChanged(doc: Document): boolean {
-  const current = documentRouteState(document)
+export function routeParamBoundaryChanged(
+  doc: Document,
+  current = documentRouteState(document),
+): boolean {
   const incoming = documentRouteState(doc)
   if (!current?.route || !incoming?.route) return false
   if (current.route !== incoming.route) return true
@@ -1118,6 +1120,10 @@ 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) {
@@ -1125,14 +1131,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') &&
@@ -1145,7 +1156,10 @@ function createNavigationPaintHold(): NavigationPaintHold | null {
   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.__pnextScroll = [window.scrollX, window.scrollY]
+  // 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%'
@@ -1181,15 +1195,13 @@ function attachNavigationPaintHold(
   // Keep that live tree visible to focus management and selector observers;
   // hiding <body> also hides every real destination element from browser gates.
   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) 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. */
@@ -1198,7 +1210,11 @@ function placeNavigationPaintHold(hold: NavigationPaintHold) {
   if (hold.__pnextScroll) hold.scrollTo?.(...hold.__pnextScroll)
 }
 
-async function releaseNavigationPaintHold(hold: NavigationPaintHold | null, reveal?: () => void) {
+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,
@@ -1206,8 +1222,17 @@ async function releaseNavigationPaintHold(hold: NavigationPaintHold | null, reve
   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)
 }
 
 /**
@@ -1581,10 +1606,13 @@ declare const __PNEXT_NEXT_ROUTER__: boolean | undefined
 // returns to where its entry was left.
 const coreNavigationScroll: NavigationScrollAction = (url, { pop, scroll }) => {
   const state = historyState()
-  const [x = 0, y = 0] = pop
-    ? (entryScroll.get(state.__pnextEntry) ?? (state.__pnextScroll as number[] | undefined) ?? [])
-    : []
-  const target = !pop && url.hash && document.getElementById(decodeURIComponent(url.hash.slice(1)))
+  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)
 }
@@ -2317,6 +2345,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)
@@ -2567,6 +2597,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. */
@@ -2586,6 +2618,8 @@ export interface PrefetchEntry {
   /** Slot-only key of the nav state the entry was rendered against. */
   slotsKey: string
   onInvalidate: (() => void)[]
+  /** A core prefetch's streamed shell, painted by a click that attaches before the body lands. */
+  shell?: { html?: string; listeners: Set<(html: string) => void> }
 }
 
 const prefetchCache = new Map<string, PrefetchEntry>()
@@ -3015,10 +3049,20 @@ export function prefetchRoute(
   options.element?.dispatchEvent(new CustomEvent('pnext:prefetchstart'))
   const startEpoch = routerCacheEpoch()
   const task = createPrefetchTask(cacheKey, options)
+  // A core prefetch is the destination document itself, so its shell can paint an attached click.
+  const shell: PrefetchEntry['shell'] =
+    typeof __PNEXT_NEXT_ROUTER__ === 'undefined' ? { listeners: new Set() } : undefined
   const page = fetchPage(url.href, {
     prefetch: full ? 'full' : 'auto',
     navState: prefetchState,
     task,
+    onShell:
+      typeof __PNEXT_NEXT_ROUTER__ === 'undefined' && !full
+        ? html => {
+            shell!.html = html
+            shell!.listeners.forEach(listener => listener(html))
+          }
+        : undefined,
     // Only when the shell is actually cached: the server strips it from the
     // response, so without a local copy there would be nothing to merge into.
     resumeFromShell: options.hoverResume === true && takeShellForUrl(url) !== null,
@@ -3107,6 +3151,7 @@ export function prefetchRoute(
     slotsKey: slotsStateKey(prefetchState.slots ?? {}),
     settled: false,
     onInvalidate: options.onInvalidate ? [options.onInvalidate] : [],
+    shell,
   })
   void page.then(fetched => {
     const entry = prefetchCache.get(cacheKey)
@@ -3114,8 +3159,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.
@@ -3259,6 +3306,7 @@ function streamHasPendingHole(buffer: string) {
 export async function readStreamedBody(
   response: Response,
   onShell: (shellHtml: string) => void,
+  ready?: (shellHtml: string) => boolean,
 ): Promise<string> {
   const reader = response.body?.getReader()
   if (!reader) return response.text()
@@ -3279,7 +3327,7 @@ export async function readStreamedBody(
       // the caller swap the complete, materialized document.
       !/<\/html>\s*$/.test(shellBuffer)
     ) {
-      if (streamHasPendingHole(shellBuffer)) {
+      if (streamHasPendingHole(shellBuffer) && (!ready || ready(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.
@@ -3406,7 +3454,7 @@ async function fetchPage(
   // Only the streamed-navigation read path (readStreamedBody) can consume a
   // late metadata tail written after `</html>`, so only it asks for one: the
   // server keeps blocking on `generateMetadata` for every other consumer.
-  if (options.onShell) headers[LATE_METADATA_HEADER] = '1'
+  if (options.onShell && !options.prefetch) headers[LATE_METADATA_HEADER] = '1'
   if (options.fullRender) headers['x-pnext-full-render'] = '1'
   if (options.resumeFromShell) headers['x-pnext-resume-shell'] = '1'
 
@@ -3675,7 +3723,16 @@ async function fetchPage(
       segmentPayload && shellOnly && !response.headers.has(SEGMENT_ROUTE_HEADER)
     const responseBody =
       strippedBody ??
-      (options.onShell ? await readStreamedBody(response, options.onShell) : await response.text())
+      (options.onShell
+        ? await readStreamedBody(
+            response,
+            options.onShell,
+            // A prefetch read can end mid-shell; its shell counts once the document's tail scripts land.
+            typeof __PNEXT_NEXT_ROUTER__ === 'undefined' && options.prefetch
+              ? shell => shell.includes('id="__PNEXT_NAV_STATE__"') && /<\/script>\s*$/.test(shell)
+              : undefined,
+          )
+        : await response.text())
     let html = segmentPayload ? segmentDocumentHtml(responseBody, bodySegment) : responseBody
     if (html === null) return null
     // A LAYOUT-only prefetch carries no page: compose this URL's cached page frame
@@ -4083,6 +4140,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.
@@ -4091,17 +4152,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
@@ -4470,14 +4533,41 @@ 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 at once, then refreshes in place.
-const keptCopies = new WeakSet<PrefetchedPage>()
-const REVALIDATE_AFTER_MS = 2_000
+/**
+ * The in-flight prefetch's document, or `null` once it has waited long enough. A streamed shell
+ * that paints this navigation first commits it to that prefetch, so it waits for the body.
+ */
+function attachToPrefetch(
+  entry: PrefetchEntry,
+  onShell?: (shellHtml: string) => boolean,
+): Promise<PrefetchedPage | null> {
+  return new Promise(resolve => {
+    const shell = entry.shell
+    const done = (page: PrefetchedPage | Promise<PrefetchedPage | null> | null) => {
+      clearTimeout(timer)
+      shell?.listeners.delete(paint)
+      resolve(page)
+    }
+    const paint = (html: string) => onShell?.(html) && done(entry.page)
+    const timer = setTimeout(done, UNSETTLED_PREFETCH_WAIT_MS, null)
+    void entry.page.then(done)
+    if (shell?.html) paint(shell.html)
+    else shell?.listeners.add(paint)
+  })
+}
+
+// Core reuses a kept copy of a dynamic page this long; past it only the copy's frame paints.
+const KEPT_DATA_MS = 5_000
+
+function keptDataFresh(entry: PrefetchEntry, now: number): boolean {
+  return !entry.settled || now - (entry.settledTime ?? entry.time) < KEPT_DATA_MS
+}
 
 async function pageForNavigation(
   url: URL,
   options: SoftNavigateOptions = {},
-  onShell?: (shellHtml: string) => void,
+  /** Paints a streamed shell; true when it committed the navigation. */
+  onShell?: (shellHtml: string) => boolean,
   /**
    * Paint a cached STATIC STAGE into the live page before the dynamic-stage request goes
    * out. Unlike `onShell` this markup is not a loading fallback but the route's real static
@@ -4514,11 +4604,17 @@ async function pageForNavigation(
       pageFrame.eligible = false
     onStaticStage?.(html, postponedShell)
   }
-  const cached = prefetchEntriesForNavigation(key).find(
+  const usable = prefetchEntriesForNavigation(key).filter(
     entry =>
       entryMatchesNavState(entry, departureNavState) &&
       (!entry.settled || now - entry.time < entry.staleTimeMs),
   )
+  // Core prefers a kept copy whose data is still fresh.
+  const cached =
+    (typeof __PNEXT_NEXT_ROUTER__ === 'undefined' &&
+      !prefetchStaleTimePolicy &&
+      usable.find(entry => keptDataFresh(entry, now))) ||
+    usable[0]
   // Popstate restores a history entry's own parallel-route state; a prefetched response was
   // rendered against the pre-navigation state and may not match, so back/forward always
   // fetches. A refresh bypasses the cache entirely.
@@ -4539,15 +4635,21 @@ async function pageForNavigation(
     const page =
       cached.settled || cached.full
         ? await cached.page
-        : await Promise.race([cached.page, unsettledPrefetchDeadline()])
+        : typeof __PNEXT_NEXT_ROUTER__ === 'undefined'
+          ? await attachToPrefetch(cached, onShell)
+          : await Promise.race([cached.page, unsettledPrefetchDeadline()])
     if (page && !page.shellOnly) {
       if (
         typeof __PNEXT_NEXT_ROUTER__ === 'undefined' &&
         !prefetchStaleTimePolicy &&
-        now - cached.time > REVALIDATE_AFTER_MS
-      )
-        keptCopies.add(page)
-      return page
+        !keptDataFresh(cached, now) &&
+        !documentStaticHintFromHtml(page.html)?.isStatic
+      ) {
+        // Next's way past the data window: paint the frame (loading fallbacks included), fetch the data.
+        const frame = sliceShell(page.html)
+        // The response shell is this frame's twin; painting it again would swap the same layout.
+        if (frame !== null && onShell?.(frame)) onShell = () => false
+      } else 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
@@ -5110,17 +5212,23 @@ 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
+  // The route whose islands a stage paint mounted; the commit keeps them instead of remounting.
+  let paintedRoute: BrowserRouteState | undefined
+  // A painted loading boundary or stage is a committed navigation state.
+  const commitPaint = () => {
+    paintedRoute = window.__PNEXT_ROUTE__
+    pushOptimisticUrl()
+    scheduleNavigationScroll(url, options)
+  }
   const devSoftNavigation = nextDevDocument()
   const onShell =
     restorePage || options.pop || refreshLike
       ? undefined
       : (shellHtml: string) => {
-          if (cachedStagePainted) return
-          if (devSoftNavigation) return
-          if (!showLoadingShell(shellHtml, sequence, url, undefined, false, true)) return
-          // A loading boundary is a committed navigation state.
-          pushOptimisticUrl()
-          scheduleNavigationScroll(url, options)
+          if (cachedStagePainted || devSoftNavigation) return false
+          if (!showLoadingShell(shellHtml, sequence, url, undefined, false, true)) return false
+          commitPaint()
+          return true
         }
   // The per-segment cache's answer for this navigation, looked up ONCE: it decides both
   // whether the generic loading shell should paint (a real cached static segment is strictly
@@ -5140,8 +5248,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
         if (devSoftNavigation) return
         if (!commitStaticStage(html, sequence, url, postponedShell)) return
         cachedStagePainted = true
-        pushOptimisticUrl()
-        scheduleNavigationScroll(url, options)
+        commitPaint()
       }
     : undefined
   // Loading-shell reuse: when the navigation must fetch, paint the CACHED shell for the
@@ -5174,8 +5281,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
         : false
     if (shellPainted) {
       cachedStagePainted = true
-      pushOptimisticUrl()
-      scheduleNavigationScroll(url, options)
+      commitPaint()
     }
   }
   // Which navigations may fetch the PAGE frame alone. Never on popstate (a history entry
@@ -5348,7 +5454,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // would compare the destination with itself and hide every param transition.
   const parallelSlotsChanged = navSlotsChanged(doc)
   const remountPageIslands =
-    (options.pop && !parallelSlotsChanged) || routeParamBoundaryChanged(doc)
+    (options.pop && !parallelSlotsChanged) || routeParamBoundaryChanged(doc, paintedRoute)
   const committedRoute = documentRouteState(doc)
   if (committedRoute) window.__PNEXT_ROUTE__ = committedRoute
 
@@ -5449,13 +5555,13 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // 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()
-  // 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)
+  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.
@@ -5569,7 +5675,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
       }
     }
   } finally {
-    await releaseNavigationPaintHold(paintHold, () => {
+    await releaseNavigationPaintHold(paintHold, sequence, () => {
       if (!url.hash && !stylesheetReconciler && sequence === navigationSequence)
         pruneStylesheets(doc)
     })
@@ -5605,23 +5711,6 @@ 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) &&
-    !documentStaticHintFromHtml(page.html)?.isStatic
-  )
-    void revalidateCommittedPage(targetUrl, sequence, page)
-}
-
-async function revalidateCommittedPage(url: URL, sequence: number, page: PrefetchedPage) {
-  const fresh = await fetchPage(url.href, { fullRender: true }).catch(() => null)
-  if (!fresh?.ok || fresh.html === page.html || sequence !== navigationSequence) return
-  await softNavigate(url.href, {
-    replace: true,
-    scroll: false,
-    refreshLike: true,
-    cachedPage: fresh,
-  })
 }
 
 function isBotUserAgent() {

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/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