@wular/pnext 0.1.1 → 0.1.2

package/package.json

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

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

@@ -1118,6 +1118,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 +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') &&
@@ -1145,7 +1154,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 +1193,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 +1208,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 +1220,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 +1604,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 +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)
@@ -2567,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. */
@@ -3114,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.
@@ -4083,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.
@@ -4091,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
@@ -4470,8 +4508,8 @@ 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>()
+// 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(
@@ -4544,9 +4582,12 @@ async function pageForNavigation(
       if (
         typeof __PNEXT_NEXT_ROUTER__ === 'undefined' &&
         !prefetchStaleTimePolicy &&
-        now - cached.time > REVALIDATE_AFTER_MS
-      )
-        keptCopies.add(page)
+        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:
@@ -5449,13 +5490,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 +5610,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,16 +5646,12 @@ 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
-  )
+  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 fetchPage(url.href, { fullRender: true }).catch(() => null)
+  const fresh = await keptCopies.get(page)
   if (!fresh?.ok || fresh.html === page.html || sequence !== navigationSequence) return
   await softNavigate(url.href, {
     replace: true,

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