@wular/pnext 0.0.6 → 0.0.8

package/src/cli/analyze.ts

@@ -9,7 +9,6 @@ import { listFiles } from '../utils/fs'
 import type { BuildManifest, RouteManifestEntry } from '../types'
 
 export interface AnalyzeResult {
-  mode: 'production' | 'development'
   root: string
   compression: AnalyzeCompression
   files: AnalyzeFile[]
@@ -43,6 +42,10 @@ export interface AnalyzeBundleFile {
 }
 
 export interface AnalyzeDynamicBundleFile extends AnalyzeBundleFile {
+  /** Island's client-reference id, as emitted in the entry's island table. */
+  id: string
+  /** Display name: the reference's named export, or its module basename. */
+  component: string
   exportName: string
   load: 'render' | 'visible'
 }
@@ -63,11 +66,10 @@ export async function analyzeProject(
     throw new Error(`No PNext output found at ${config.outPath}. Run pnext build first.`)
   }
 
+  // Dev output is unminified, so its sizes say nothing about what ships; analyze is production-only.
   const target = analyzeTarget(config.outPath)
   if (!target) {
-    throw new Error(
-      `No PNext build or dev output found at ${config.outPath}. Run pnext build or pnext dev first.`,
-    )
+    throw new Error(`No production build found at ${config.outPath}. Run pnext build first.`)
   }
 
   const compression = options.compression ?? 'gzip'
@@ -83,13 +85,9 @@ export async function analyzeProject(
       }
     }),
   )
-  const routeBundles =
-    target.mode === 'production'
-      ? await analyzeRouteBundles(config.outPath, target.root, rows, options.route)
-      : []
+  const routeBundles = await analyzeRouteBundles(config.outPath, target.root, rows, options.route)
 
   return {
-    mode: target.mode,
     root: path.relative(config.root, target.root),
     compression,
     files: rows,
@@ -115,7 +113,9 @@ async function analyzeRouteBundles(
 
   const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as BuildManifest
   const pages = manifest.routes.filter(route => route.kind === 'page')
-  const selected = routeFilter ? filterAnalyzeRoutes(pages, routeFilter) : pages
+  const selected: AnalyzeRouteSelection[] = routeFilter
+    ? filterAnalyzeRoutes(pages, routeFilter)
+    : pages.map(route => ({ route }))
   if (routeFilter && selected.length === 0) {
     throw new Error(
       `No route matches ${routeFilter}. Routes:\n  ${pages
@@ -135,22 +135,29 @@ async function analyzeRouteBundles(
   }
 
   const bundles: AnalyzeRouteBundle[] = []
-  for (const route of selected) {
-    bundles.push(await analyzeRouteBundle(route, sizes, js))
+  for (const { route, pathname } of selected) {
+    bundles.push(await analyzeRouteBundle(route, sizes, js, pathname))
   }
   return bundles
 }
 
+interface AnalyzeRouteSelection {
+  route: RouteManifestEntry
+  /** Concrete pathname the filter matched, for a param route's prerendered HTML. */
+  pathname?: string
+}
+
 // Accepts the route in ':id' or '[id]' template form, or a concrete pathname
-// (e.g. /users/ada) matched through the route patterns.
-function filterAnalyzeRoutes(pages: RouteManifestEntry[], filter: string) {
+// (e.g. /users/ada) matched through the route patterns. A concrete pathname is
+// carried through so the bundle reports that page's prerendered HTML.
+function filterAnalyzeRoutes(pages: RouteManifestEntry[], filter: string): AnalyzeRouteSelection[] {
   const normalized = filter === '/' ? filter : filter.replace(/\/+$/, '')
   const direct = pages.filter(
     route => route.route === normalized || publicRoutePath(route.route) === normalized,
   )
-  if (direct.length > 0) return direct
+  if (direct.length > 0) return direct.map(route => ({ route }))
   const matched = matchRoute(pages, normalized)
-  return matched ? [matched.route] : []
+  return matched ? [{ route: matched.route, pathname: normalized }] : []
 }
 
 function publicRoutePath(route: string) {
@@ -161,14 +168,30 @@ async function analyzeRouteBundle(
   route: RouteManifestEntry,
   sizes: Map<string, AnalyzeFile>,
   js: (path: string) => Promise<string>,
+  pathname?: string,
 ): Promise<AnalyzeRouteBundle> {
   const initial = new Set<string>()
-  addIfExists(initial, sizes, routeHtmlPath(route))
+  addIfExists(initial, sizes, routeHtmlPath(route, pathname))
   addIfExists(initial, sizes, 'assets/global.css')
-  addIfExists(initial, sizes, `assets/${route.id}.css`)
+  // Mirrors the renderer's stylesheet list: compat cssChunking splits a route's
+  // CSS into `<id>-<n>.css` and records them in cssAssets; `<id>.css` is emitted
+  // only when it is unset.
+  for (const asset of route.cssAssets ?? (route.cssImports.length ? [`${route.id}.css`] : []))
+    addIfExists(initial, sizes, `assets/${asset}`)
+  // Every compat page loads this with a blocking <script>. The sibling
+  // `_ssgManifest.js` (router-fetched, never in the document) and the
+  // `polyfills-*.js` chunk (noModule: legacy browsers only) are deliberately
+  // not initial weight for a modern client.
+  addIfExists(initial, sizes, '_next/static/pnext/_buildManifest.js')
 
   if (route.clientEntry) {
     addIfExists(initial, sizes, route.clientEntry)
+    // The build records the entry's chunk closure from the esbuild metafile and
+    // the renderer modulepreloads exactly this set. Chunk folding hoists imports
+    // out of the entry module, so walking its source alone under-reports; the
+    // walk stays as a union for dev-style single-bundle entries, which never
+    // populate clientEntryImports.
+    for (const asset of route.clientEntryImports ?? []) addIfExists(initial, sizes, asset)
     for (const dependency of await staticDependencies(route.clientEntry, sizes, js))
       initial.add(dependency)
   }
@@ -180,17 +203,21 @@ async function analyzeRouteBundle(
 
   if (route.clientEntry && sizes.has(toPosix(route.clientEntry))) {
     const entrySource = await js(route.clientEntry)
-    const imports = dynamicImports(entrySource, route.clientEntry)
-    for (const imported of imports) {
-      const reference = route.clientReferences.find(item => item.exportName === imported.exportName)
+    for (const island of islandImports(entrySource, route.clientEntry)) {
+      const row = sizes.get(island.path)
+      if (!row) continue
+      // Keyed by island id: every island's loader resolves `module.default`, so
+      // matching on the export name collapses them all onto one reference.
+      const reference = route.clientReferences.find(item => item.id === island.id)
       const load: AnalyzeDynamicBundleFile['load'] =
         reference?.dynamic?.load === 'visible' ? 'visible' : 'render'
-      const row = sizes.get(imported.path)
-      if (!row) continue
-      dynamicTargets.add(imported.path)
+      dynamicTargets.add(island.path)
+      const exportName = reference?.exportName ?? 'default'
       const item: AnalyzeDynamicBundleFile = {
-        path: imported.path,
-        exportName: imported.exportName,
+        path: island.path,
+        id: island.id,
+        component: islandComponent(exportName, reference?.file, island.path),
+        exportName,
         load,
         rawBytes: row.rawBytes,
         compressedBytes: row.compressedBytes,
@@ -198,12 +225,22 @@ async function analyzeRouteBundle(
       if (load === 'visible') visibleDynamic.push(item)
       else dynamic.push(item)
 
-      for (const dependency of await staticDependencies(imported.path, sizes, js)) {
+      // An island with its own CSS loads `assets/<referenceId>.css` alongside its
+      // chunk (loadIslandCss); it is deferred weight, so it belongs here rather
+      // than in initial.
+      if (reference?.cssImports?.length) addIfExists(lazyShared, sizes, `assets/${island.id}.css`)
+      for (const dependency of await staticDependencies(island.path, sizes, js)) {
         if (!initial.has(dependency) && !dynamicTargets.has(dependency)) lazyShared.add(dependency)
       }
     }
 
-    for (const importedPath of dynamicImportPaths(entrySource, route.clientEntry)) {
+    // Same metafile closure as the renderer's low-priority preloads, unioned
+    // with the entry-source walk for the same reason as the static side above.
+    for (const asset of [
+      ...(route.clientDynamicImports ?? []),
+      ...dynamicImportPaths(entrySource, route.clientEntry),
+    ]) {
+      const importedPath = toPosix(asset)
       if (initial.has(importedPath) || dynamicTargets.has(importedPath)) continue
       if (sizes.has(importedPath)) lazyShared.add(importedPath)
       for (const dependency of await staticDependencies(importedPath, sizes, js)) {
@@ -222,6 +259,12 @@ async function analyzeRouteBundle(
   }
 }
 
+function islandComponent(exportName: string, file: string | undefined, chunkPath: string) {
+  if (exportName !== 'default') return exportName
+  const source = file ?? chunkPath.replace(/-[A-Z0-9]{8}\.js$/, '.js')
+  return path.posix.basename(toPosix(source)).replace(/\.[^.]+$/, '')
+}
+
 async function staticDependencies(
   entry: string,
   sizes: Map<string, AnalyzeFile>,
@@ -244,17 +287,22 @@ async function staticDependencies(
   return dependencies
 }
 
-function dynamicImports(source: string, from: string) {
-  const imports: { path: string; exportName: string }[] = []
+// Entries of the entry module's island table, as emitted by client/entry.ts:
+//   { id: "c-...", options: {...}, load: () => import("./chunk.js").then(m => m.default) }
+// The CSS variant wraps the import in `Promise.all([...])`. Statically-bundled
+// islands carry `Component:` instead of `load:` and are part of the entry's own
+// closure, so they are not matched here.
+function islandImports(source: string, from: string) {
+  const imports: { path: string; id: string }[] = []
   const pattern =
-    /import\("([^"]+)"\)\.then\([A-Za-z_$][\w$]*=>[A-Za-z_$][\w$]*\.([A-Za-z_$][\w$]*)\)/g
+    /\bid\s*:\s*"([^"]+)"\s*,\s*options\s*:\s*\{[^{}]*\}\s*,\s*load\s*:\s*\(\)\s*=>\s*(?:Promise\.all\(\[\s*)?import\(\s*"([^"]+)"\s*\)/g
   let match: RegExpExecArray | null
   while ((match = pattern.exec(source))) {
-    const specifier = match[1]
-    const exportName = match[2]
-    if (!specifier || !exportName) continue
+    const id = match[1]
+    const specifier = match[2]
+    if (!id || !specifier) continue
     const resolved = resolveBuiltImport(from, specifier)
-    if (resolved) imports.push({ path: resolved, exportName })
+    if (resolved) imports.push({ path: resolved, id })
   }
   return imports
 }
@@ -306,18 +354,27 @@ function bundleFiles(paths: string[], sizes: Map<string, AnalyzeFile>) {
     .sort((a, b) => b.compressedBytes - a.compressedBytes)
 }
 
-function routeHtmlPath(route: RouteManifestEntry) {
-  return route.route === '/' ? 'index.html' : `${route.route.replace(/^\/+/, '')}/index.html`
+function routeHtmlPath(route: RouteManifestEntry, pathname?: string) {
+  const target = pathname ?? prerenderedPathname(route) ?? route.route
+  return target === '/' ? 'index.html' : `${target.replace(/^\/+/, '')}/index.html`
+}
+
+// A param route prerenders one file per param set, never `posts/:slug/index.html`.
+// Report the first as the representative page instead of dropping HTML entirely.
+function prerenderedPathname(route: RouteManifestEntry) {
+  const params = route.prerenderedParams?.[0]
+  if (!params) return undefined
+  return route.route.replace(/:([a-zA-Z0-9_]+)\*?/g, (_match, name: string) => {
+    const value = params[name]
+    return Array.isArray(value) ? value.join('/') : (value ?? '')
+  })
 }
 
 function analyzeTarget(outPath: string) {
+  // PPR shells live in `.pnext/ppr`, outside `public`: they are resumed
+  // server-side and never downloaded, so they are not shipped weight.
   const publicPath = path.join(outPath, 'public')
-  if (existsSync(publicPath)) return { mode: 'production' as const, root: publicPath }
-
-  const cachePath = path.join(outPath, 'cache')
-  if (existsSync(cachePath)) return { mode: 'development' as const, root: cachePath }
-
-  return null
+  return existsSync(publicPath) ? { root: publicPath } : null
 }
 
 function compressedSize(bytes: Buffer, compression: AnalyzeCompression) {
@@ -344,9 +401,7 @@ export function printAnalyzeResult(
   result: AnalyzeResult,
   options: { route?: string; files: boolean },
 ) {
-  console.log(
-    `PNext analyze: ${result.mode === 'production' ? 'production build' : 'dev server cache'} at ${dim(result.root)} (${result.compression})`,
-  )
+  console.log(`PNext analyze: production build at ${dim(result.root)} (${result.compression})`)
   printRouteBundles(result)
   // With a route filter, the remaining files are mostly other routes' bundles —
   // listing them as "other" would misread as unowned weight.
@@ -385,11 +440,11 @@ function printDynamicBundleGroup(
   if (files.length === 0) return
   console.log(`\n  ${bold(label)}`)
   const columns = rowColumns(files)
-  const componentWidth = Math.max(...files.map(file => file.exportName.length))
+  const componentWidth = Math.max(...files.map(file => file.component.length))
   const pathWidth = Math.max(...files.map(file => file.path.length))
   for (const file of files) {
     console.log(
-      `    ${file.exportName.padEnd(componentWidth)}  ${dim(file.path.padEnd(pathWidth))}  ${formatFileSize(file, compression, columns)}`,
+      `    ${file.component.padEnd(componentWidth)}  ${dim(file.path.padEnd(pathWidth))}  ${formatFileSize(file, compression, columns)}`,
     )
   }
 }

package/src/cli/create.ts

@@ -149,6 +149,6 @@ function scaffoldFiles(name: string): Record<string, string> {
     'app/counter.tsx': `'use client';\n\nimport { useState } from 'preact/hooks';\n\nexport default function Counter() {\n  const [count, setCount] = useState(0);\n  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;\n}\n`,
     'app/globals.css': `body {\n  margin: 0;\n  font-family: system-ui, sans-serif;\n}\n`,
     '.gitignore': `node_modules\n.pnext\n`,
-    'README.md': `# ${name}\n\nA pnext app.\n\n\`\`\`\nbun install\nbun dev\n\`\`\`\n\nDocs: node_modules/@wular/pnext/reference/overview.md\n`,
+    'README.md': `# ${name}\n\nA pnext app.\n\n\`\`\`\nbun install\nbun dev\n\`\`\`\n\nDocs: node_modules/@wular/pnext/reference/getting-started.md\n`,
   }
 }

package/src/cli/index.ts

@@ -4,6 +4,12 @@ import path from 'node:path'
 import { markBoot } from './boot/trace'
 import { commandBinaryName, nameEsbuildProcess, namedBunBinary } from './boot/named-bin'
 
+// Reached only if something bypassed bin/pnext (which guards the same way).
+if (typeof Bun === 'undefined') {
+  console.error('pnext requires Bun. Install it from https://bun.sh/get')
+  process.exit(1)
+}
+
 const [, , command, ...args] = process.argv
 markBoot('cli:entry')
 

package/src/client/build.ts

@@ -16,7 +16,7 @@ import {
 import { foldInitialChunks } from './chunk-fold'
 import { clientEntryName } from './chunk-name'
 import { clientProfile } from './profile'
-import { publicEnvDefines, type ResolvedConfig } from '../config'
+import { frameworkRuntimeAliasEntries, publicEnvDefines, type ResolvedConfig } from '../config'
 import { cssModuleClientPlugin } from '../css/build'
 import { withAssetPrefix } from '../css/build'
 import {
@@ -1220,7 +1220,15 @@ function clientBuildPlugins(
 }
 
 function importAliasPlugin(config: ResolvedConfig, reactLite = false): Plugin {
-  const aliases = { ...getImportAliasExtensions().aliases(config, 'client') }
+  // preact core/hooks/jsx-runtime are single-instance, compat or not: an app with its
+  // own `preact` in node_modules otherwise bundles a second physical copy next to the
+  // framework's, and hooks called from framework components (Link) read a null current
+  // component off options the app's copy never installed. The server runtime pins the
+  // same set unconditionally (loader's coreAliases); the client build must match.
+  const aliases: Record<string, string> = {
+    ...frameworkRuntimeAliasEntries(),
+    ...getImportAliasExtensions().aliases(config, 'client'),
+  }
   // Suspense-free tier: the app's `react` imports resolve to the compat-free lite shim, so the
   // bundle ships preact core + hooks without preact/compat (see clientSuspenseFree).
   if (reactLite && aliases.react) {

package/src/client/entry.ts

@@ -91,7 +91,9 @@ function islandContextModulePath() {
 // Wire-marker revival shared with the server encoder (utils/serialize.ts):
 // island props carrying a CYCLE travel as `$$pnext_ref` back-references.
 function staticSlotsModulePath() {
-  return path.join(import.meta.dirname, '../render/static-slots.ts')
+  // The preact-free half: entries import it eagerly, so it must not drag preact into a
+  // visible-dynamic entry's static graph.
+  return path.join(import.meta.dirname, '../render/static-slots-revive.ts')
 }
 
 function serializeModulePath() {
@@ -296,10 +298,12 @@ import { hasIslandStaticSlots as __pnextHasIslandSlots, reviveIslandStaticSlots
 // Element-valued props: the wire carries a \`$$pnext_slot\` id per element and the server rendered it
 // inside a matching \`pnext-static-slot\` host, adopted here exactly like element children. Islands
 // with no element props skip the walk on a substring test of the raw attribute.
-function islandProps(raw, root, toChildren) {
+// \`h\` is threaded in rather than imported by the slot reviver: that would put preact in the static
+// graph of entries (visible-dynamic) that otherwise only lazy-import it.
+function islandProps(raw, root, toChildren, h) {
   const props = parseIslandProps(raw);
   if (!__pnextHasIslandSlots(raw)) return props;
-  return __pnextReviveIslandSlots(props, root, toChildren);
+  return __pnextReviveIslandSlots(props, root, toChildren, h);
 }
 function parseIslandProps(raw) {
   const props = JSON.parse(raw || '{}');${
@@ -978,7 +982,7 @@ async function mountIslandTree(root, island) {
   ]);
 ${facts.suspense !== false ? '  islandBoundary = Suspense;\n' : ''}  const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
-  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node)), await staticChildren(h, source, island.id));
+  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id));
   const wrapped = ${facts.suspense !== false ? 'h(Suspense, { fallback: null }, pnextClientBoundary(h, vnode))' : 'pnextClientBoundary(h, vnode)'};
   if (source !== root) adoptPreserved(render, root, wrapped);
   else mount(hydrate, render, root, wrapped);
@@ -991,7 +995,7 @@ async function mountIslandTree(root, island) {
   const [{ h, hydrate, render }, Component] = await Promise.all([import('preact'), island.load()]);
   const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
-  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node)), await staticChildren(h, source, island.id));
+  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id));
   if (source !== root) adoptPreserved(render, root, vnode);
   else mount(hydrate, render, root, vnode);
 }`
@@ -1077,7 +1081,7 @@ async function domNode(h, node) {
     if (!island) return h(element.localName, domProps(element), await domChildren(h, element));
     const Component = island.Component ?? await island.load();
     const rawProps = element.getAttribute('data-pnext-props') ?? '{}';
-    const vnode = islandVNode(h, Component, await islandProps(rawProps, element, node => domChildren(h, node)), await staticChildren(h, element, island.id));
+    const vnode = islandVNode(h, Component, await islandProps(rawProps, element, node => domChildren(h, node), h), await staticChildren(h, element, island.id));
     return ${nextCompat ? 'islandBoundary ? h(islandBoundary, { fallback: null }, pnextClientBoundary(h, vnode)) : pnextClientBoundary(h, vnode)' : 'vnode'};
   }
 
@@ -1364,7 +1368,7 @@ async function mountIslandTree(root, island) {
     // Preserved across a soft navigation: re-render in place with the incoming
     // document's props/children so component state survives while the routed
     // content under the island updates.
-    const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, incoming, domChildren)', 'await staticChildren(incoming, island.id)', 'root', nextCompat)};
+    const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, incoming, domChildren, h)', 'await staticChildren(incoming, island.id)', 'root', nextCompat)};
     render(${wrapInBoundary('vnode', nextCompat)}, root);
     pnextMountedRoots.add(root);
     return;
@@ -1375,7 +1379,7 @@ async function mountIslandTree(root, island) {
     root.replaceChildren(...incoming.childNodes);
     root.__pnextLive = undefined;
   }
-  const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, root, domChildren)', 'await staticChildren(root, island.id)', 'root', nextCompat)};
+  const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, root, domChildren, h)', 'await staticChildren(root, island.id)', 'root', nextCompat)};
   mount(root, ${wrapInBoundary('vnode', nextCompat)});
 }
 
@@ -1448,7 +1452,7 @@ async function domNode(node) {
         : ''
     }
     const Component = island.Component ?? await island.load();
-    return ${wrapInBoundary(islandVNodeExpr('Component', 'await islandProps(rawProps, element, domChildren)', 'children', 'element', nextCompat), nextCompat)};
+    return ${wrapInBoundary(islandVNodeExpr('Component', 'await islandProps(rawProps, element, domChildren, h)', 'children', 'element', nextCompat), nextCompat)};
   }
 
   if (Page && element.id === 'pnext-page') {

package/src/client/router/events.ts

@@ -22,9 +22,24 @@ export function locationListeners() {
 
 export function emitLocationChange() {
   routerState.observedLocationKey = locationKey()
+  if (silentLocationDepth > 0) return
   for (const listener of [...locationListeners()]) listener()
 }
 
+let silentLocationDepth = 0
+
+// Moves the address bar without waking usePathname/useParams subscribers: the pre-commit
+// optimistic push's URL is ahead of the tree, so broadcasting would desync URL and params.
+// observedLocationKey still advances, so a traversal off the pushed entry is a real move.
+export function withSilentLocationChange(move: () => void) {
+  silentLocationDepth++
+  try {
+    move()
+  } finally {
+    silentLocationDepth--
+  }
+}
+
 // Fires at the start of every soft navigation (link click, router.push,
 // refresh). Compat's link-status uses it to end a link's pending state when a
 // different navigation supersedes it.

package/src/client/router/runtime.ts

@@ -31,11 +31,13 @@ import {
   emitNavigationCommit,
   emitNavigationStart,
   scheduleNavigationScroll,
+  withSilentLocationChange,
 } from './events'
 import type {
   ClientPageRoot,
   DocumentNavState,
   EntryModule,
+  LinkPrefetchMode,
   LoadingShellPrediction,
   PrefetchedPage,
   PrefetchOptions,
@@ -4059,9 +4061,13 @@ async function pageForNavigation(
     // Reuse within the staleTime window (the entry is kept warm, not one-shot). A failed
     // entry is dropped. A shell-only (partial prefetch) entry never commits as a document -
     // its loading shell was painted above; fall through to the real fetch.
-    const page = cached.settled
-      ? await cached.page
-      : await Promise.race([cached.page, unsettledPrefetchDeadline()])
+    // A full (`prefetch={true}`) prefetch is a complete document for this navigation:
+    // attach to it on its own settle signal (cancel/error resolve null), never a wall
+    // clock - a slow machine must not make the router duplicate the request.
+    const page =
+      cached.settled || cached.full
+        ? await cached.page
+        : await Promise.race([cached.page, unsettledPrefetchDeadline()])
     if (page && !page.shellOnly) 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
@@ -4523,14 +4529,24 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // shallow same-entry move in onPopState and get dropped, stranding the UI on the
   // half-committed target. The commit below reuses the id.
   let optimisticEntryId: string | undefined
-  const pushOptimisticUrl = () => {
+  // `silent` moves the address bar without broadcasting: used before the tree is painted, where a
+  // location broadcast would render the destination URL against the departing route's params.
+  const pushOptimisticUrl = (silent = false) => {
     if (optimisticallyPushed || options.pop || refreshLike) return
     if (url.pathname === location.pathname && url.search === location.search) return
     optimisticallyPushed = true
     optimisticEntryId = routerState.renderedEntryId = newEntryId()
     const shellState = { ...historyState(), __pnextEntry: optimisticEntryId }
-    if (options.replace) history.replaceState(shellState, '', url.href)
-    else history.pushState(shellState, '', url.href)
+    const move = () => {
+      if (options.replace) history.replaceState(shellState, '', url.href)
+      else history.pushState(shellState, '', url.href)
+    }
+    if (silent) withSilentLocationChange(move)
+    else move()
+    // Record the observed URL without emitting; a stale key would make a back() off this
+    // entry compare equal to the departing URL and read as a shallow move, so onPopState
+    // would leave the DOM alone and this navigation would paint over the popped entry.
+    routerState.observedLocationKey = locationKey()
   }
   // A forward navigation to a route with a loading boundary streams shell-first, so paint
   // that fallback into the current page container as soon as the shell chunk arrives. Skipped
@@ -4696,6 +4712,12 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
     return
   }
 
+  // All hard-navigate bailouts are behind us: open the history entry NOW, before the asset
+  // warm-up awaits the network - a back() in that window would otherwise escape the app
+  // (no entry pushed yet). The final commit replaces this entry, correcting redirects. Silent:
+  // nothing has painted yet, so subscribers must keep seeing the departing route until commit.
+  pushOptimisticUrl(true)
+
   // Warm the new document's assets before touching the current one: the swap
   // then paints styled content immediately instead of flashing unstyled HTML.
   const entrySrc = entryScriptSrc(doc)
@@ -5005,6 +5027,16 @@ function isFullPrefetchLink(link: Element): boolean {
   return link.getAttribute('data-prefetch-full') === 'true'
 }
 
+// The mode a link prefetches in. Its own `data-prefetch` always wins; a plain
+// `data-pnext-link` anchor without one takes the app-wide config default
+// (`window.__PNEXT_PREFETCH__`, injected by the server), else 'visible'.
+export function linkPrefetchMode(link: Element): LinkPrefetchMode {
+  const attribute = link.getAttribute('data-prefetch')
+  if (attribute === null)
+    return (typeof window === 'undefined' ? undefined : window.__PNEXT_PREFETCH__) ?? 'visible'
+  return attribute === 'false' ? false : (attribute as LinkPrefetchMode)
+}
+
 // Pointer-intent state. True once the pointer has moved since the last pointerdown -
 // distinguishes a real hover from content swapping in under a stationary cursor. Starts true
 // so a hover before any click counts. Because boundary events precede the pointermove of the
@@ -5029,8 +5061,7 @@ function onLinkIntent(event: Event) {
   }
   const link = linkFromEvent(event)
   if (!link) return
-  const mode = link.getAttribute('data-prefetch')
-  if (mode === 'false') return
+  if (linkPrefetchMode(link) === false) return
   const href = link.getAttribute('href')
   // unstable_dynamicOnHover: hover intent upgrades the partial (viewport)
   // prefetch to a full one carrying the dynamic data — served as a resume-only
@@ -5128,7 +5159,7 @@ function scanEagerPrefetchLinks(root: Element) {
   const links = [...root.querySelectorAll<HTMLAnchorElement>('a[data-pnext-link]')]
   if (root.matches('a[data-pnext-link]')) links.push(root as HTMLAnchorElement)
   for (const link of links) {
-    const mode = link.getAttribute('data-prefetch')
+    const mode = linkPrefetchMode(link)
     if (mode !== 'load' && mode !== 'visible') continue
     if (eagerLinks.has(link)) continue
     eagerLinks.add(link)

package/src/client/router/types.ts

@@ -152,8 +152,13 @@ export interface EntryModule {
   mountRoute?: () => Promise<unknown> | void
 }
 
+/** Mirror of core's PrefetchMode; the router keeps no imports outside its chunk. */
+export type LinkPrefetchMode = false | 'intent' | 'visible' | 'load'
+
 declare global {
   interface Window {
+    /** App-wide default prefetch mode (config `prefetch`), injected by the server. */
+    __PNEXT_PREFETCH__?: LinkPrefetchMode
     __PNEXT_ROUTER_INSTALLED__?: boolean
     __PNEXT_ROUTER_IMPORTS__?: number
     __PNEXT_ACTIVE_ENTRY__?: ActiveEntry

package/src/config.ts

@@ -3,7 +3,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 import path from 'node:path'
 import { loadEnv } from './env'
 import { findWorkspaceRoot } from './resolve/imports'
-import type { PNextConfig } from './types'
+import { PREFETCH_MODES, type PNextConfig } from './types'
 import { setCacheComponents } from './render/ppr'
 
 export type ResolvedConfig = Required<Pick<PNextConfig, 'outDir' | 'basePath'>> &
@@ -86,6 +86,7 @@ export async function loadConfig(
       ? { compat: { ...(loadedConfig.default?.compat ?? {}), next: true } }
       : {}),
   }
+  validateConfig(config)
   // cacheComponents is a per-app flag on a process-global cell: clear it before
   // the next.config source re-derives it, so a pure-core (or flag-off) app
   // loaded after a cacheComponents app never inherits the previous build's flag.
@@ -128,6 +129,22 @@ export async function loadConfig(
   }
 }
 
+// One row per enum-valued config field; validateConfig checks them all.
+const enumFields: readonly [keyof PNextConfig, readonly unknown[]][] = [
+  ['prefetch', PREFETCH_MODES],
+]
+
+function validateConfig(config: PNextConfig) {
+  for (const [field, allowed] of enumFields) {
+    const value = config[field]
+    if (value === undefined || allowed.includes(value)) continue
+    const list = allowed.map(v => (typeof v === 'string' ? `'${v}'` : String(v))).join(', ')
+    throw new Error(
+      `Invalid pnext config: '${field}' must be one of ${list} (received ${JSON.stringify(value)}).`,
+    )
+  }
+}
+
 /** Dev's private subtree under the out root. Build never touches it. */
 export const devOutSegment = 'dev'
 

package/src/dev/server.ts

@@ -964,10 +964,10 @@ async function handleRoute(
 }
 
 function routeClientCacheKey(config: ResolvedConfig, route: RouteManifestEntry) {
-  const existing = routeCacheKeys.get(route.id)
+  const existing = routeCacheKeys.get(appKey(config.outPath, route.id))
   if (existing) return existing
   const key = devClientCacheKey(config, route, Boolean(config.compat?.next))
-  routeCacheKeys.set(route.id, key)
+  routeCacheKeys.set(appKey(config.outPath, route.id), key)
   return key
 }
 

package/src/render/renderer.ts

@@ -3655,6 +3655,7 @@ async function renderTree(
       renderCollectedHeadScripts(),
       bootstrapScripts,
       compatBuildManifestScript,
+      prefetchModeScript(options.config),
     ]
       .filter(Boolean)
       .join('\n'),
@@ -3791,6 +3792,16 @@ function shouldRenderRuntimeMetadataInBody(options: RenderOptions, runtimeMetada
   )
 }
 
+/**
+ * Inline script exposing the configured default prefetch mode to the client router, which applies it
+ * to links carrying no `data-prefetch` of their own. Emitted only when `prefetch` is configured - an
+ * app that leaves it unset keeps the global undefined and the built-in 'visible' default.
+ */
+function prefetchModeScript(config: ResolvedConfig): string {
+  if (config.prefetch === undefined) return ''
+  return `<script>window.__PNEXT_PREFETCH__=${JSON.stringify(config.prefetch)};</script>`
+}
+
 /**
  * Embeds the render's navigation state (children source path + each slot's
  * resolved source path). The client echoes it on soft-navigation fetches so