@wular/pnext 0.0.19 → 0.0.21

package/README.md

@@ -13,13 +13,13 @@
 A new app:
 
 ```sh
-bunx @wular/pnext create my-app
+bunx @wular/pnext@latest create my-app
 ```
 
 Migrating a Next.js app? This rewrites scripts and config in place, scans your source, and reports anything that needs a look (it never edits your code):
 
 ```sh
-bunx @wular/pnext migrate
+bunx @wular/pnext@latest migrate
 ```
 
 Or by hand: `bun add -d @wular/pnext`, then `pnext dev`.

package/package.json

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

package/reference/compat.md

@@ -19,8 +19,8 @@ To turn Next compatibility on without a config file, set `PNEXT_COMPAT=next`. Se
 ## Migrating a Next.js app
 
 ```sh
-bunx @wular/pnext migrate --dry-run
-bunx @wular/pnext migrate
+bunx @wular/pnext@latest migrate --dry-run
+bunx @wular/pnext@latest migrate
 ```
 
 Migration rewrites `package.json` and `tsconfig.json`, and creates a `pnext.config.ts` with `compat.next` enabled. It reports on your app source but never edits it.

package/reference/getting-started.md

@@ -9,7 +9,7 @@ pnext is a Preact framework for file-routed apps. It renders on the server by de
 ## New app
 
 ```sh
-bunx @wular/pnext create my-app
+bunx @wular/pnext@latest create my-app
 cd my-app
 bun dev
 ```
@@ -23,7 +23,7 @@ The app is running at `http://localhost:3000`. Edit `app/page.tsx`; the browser
 Run in your Next project:
 
 ```sh
-bunx @wular/pnext migrate
+bunx @wular/pnext@latest migrate
 ```
 
 It converts the project to pnext with `compat.next` enabled, without editing app source. `--dry-run` previews.

package/src/cli/adapters/vercel.ts

@@ -7,6 +7,7 @@ import { DEFAULT_OUT_DIR, pathToFileHref } from '../../config'
 import type { ResolvedConfig } from '../../config'
 import { globalCssSources } from '../../css/build'
 import { getImportAliasExtensions } from '../../extensions'
+import { nextCompatEnabled } from '../../render/hooks'
 import { importSpecifiers } from '../../resolve/scan-facts'
 import { compiledSpecifiersManifestSuffix } from '../../runtime/modules'
 import { resolveImport, workspacePackageRoots } from '../../resolve/imports'
@@ -199,6 +200,11 @@ export async function writeVercelOutput(
   const overrides = await staticOverrides(path.join(config.outPath, 'public'), staticFiles)
 
   const routes: NonNullable<VercelConfig['routes']> = [
+    // next-compat documents reference the build output under Next's static path (assetPathname),
+    // but it is copied to the CDN at `static/assets/*`. Rewrite before `handle: filesystem` so the
+    // 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)/.*',
@@ -246,6 +252,27 @@ async function emptyDir(dir: string) {
   }
 }
 
+/**
+ * The `/_next/static/*` -> `/assets/*` CDN rewrite for a next-compat build, restricted to the names
+ * actually copied under `assets/`. It has to be a NARROW alternation, not `(.*)`: `_next/static` is
+ * also a REAL output path (`media/*` from the static-media mirror, `pnext/_buildManifest.js`), and
+ * a blanket rewrite would point those at an `assets/` twin that does not exist.
+ */
+function compatStaticRewrite(config: ResolvedConfig, outputPath: string) {
+  if (!nextCompatEnabled(config)) return []
+  const staticDir = path.join(outputPath, 'static')
+  const names = readdirSyncSafe(path.join(staticDir, 'assets'))
+    // A name that is ALSO a real `_next/static/<name>` must keep resolving to itself.
+    .filter(name => !existsSync(path.join(staticDir, '_next', 'static', name)))
+  if (names.length === 0) return []
+  const alternation = names.map(name => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')
+  return [{ src: `^/_next/static/(${alternation})(/.*)?$`, dest: '/assets/$1$2', continue: true }]
+}
+
+function readdirSyncSafe(dir: string) {
+  return existsSync(dir) ? readdirSync(dir) : []
+}
+
 async function proxyRoutes(config: ResolvedConfig) {
   const proxyFile = findProxyFile(config)
   if (!proxyFile) return []

package/src/cli/analyze.ts

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import zlib from 'node:zlib'
 import { loadConfig } from '../config'
+import { emittedAssetName, publishEmittedAssets, routeCssAssetNames } from '../css/build'
 import { matchRoute } from '../routing/routes'
 import { bold, cyan, dim } from '../utils/ansi'
 import { listFiles } from '../utils/fs'
@@ -112,6 +113,8 @@ async function analyzeRouteBundles(
   if (!existsSync(manifestPath)) return []
 
   const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as BuildManifest
+  // Resolve the logical CSS names through the build's content-hashed spellings.
+  publishEmittedAssets(outPath, manifest.assetNames)
   const pages = manifest.routes.filter(route => route.kind === 'page')
   const selected: AnalyzeRouteSelection[] = routeFilter
     ? filterAnalyzeRoutes(pages, routeFilter)
@@ -136,7 +139,7 @@ async function analyzeRouteBundles(
 
   const bundles: AnalyzeRouteBundle[] = []
   for (const { route, pathname } of selected) {
-    bundles.push(await analyzeRouteBundle(route, sizes, js, pathname))
+    bundles.push(await analyzeRouteBundle(outPath, route, sizes, js, pathname))
   }
   return bundles
 }
@@ -165,6 +168,7 @@ function publicRoutePath(route: string) {
 }
 
 async function analyzeRouteBundle(
+  outPath: string,
   route: RouteManifestEntry,
   sizes: Map<string, AnalyzeFile>,
   js: (path: string) => Promise<string>,
@@ -172,12 +176,9 @@ async function analyzeRouteBundle(
 ): Promise<AnalyzeRouteBundle> {
   const initial = new Set<string>()
   addIfExists(initial, sizes, routeHtmlPath(route, pathname))
-  addIfExists(initial, sizes, 'assets/global.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}`)
+  const assetFile = (name: string) => `assets/${emittedAssetName({ outPath }, name)}`
+  addIfExists(initial, sizes, assetFile('global.css'))
+  for (const asset of routeCssAssetNames(route)) addIfExists(initial, sizes, assetFile(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

package/src/cli/boot/trace.ts

@@ -7,12 +7,19 @@
  * one rss read; nothing is ever printed.
  */
 import { loadavg, cpus, arch, platform } from 'node:os'
-import { existsSync, readdirSync } from 'node:fs'
+import { readdirSync } from 'node:fs'
 import path from 'node:path'
 import { traceEnabled } from '../../utils/trace-flags'
 
 const enabled = traceEnabled('boot')
 const marks: [string, number, number][] = []
+// Snapshotted at import: boot creates the cache directory long before the trace prints, so reading
+// it at print time always reported "warm" - including on a run that had just wiped it.
+const cacheAtStart = enabled ? cacheState() : 'cold'
+
+function cacheState() {
+  return countTopLevel(path.join('.pnext', 'dev', 'cache')) > 0 ? 'warm' : 'cold'
+}
 
 // Bun (<=1.3.x) lacks the memoryUsage.rss fast path Node has.
 const rss = () =>
@@ -31,10 +38,9 @@ function traceHeader(): string[] {
     .map(value => value.toFixed(1))
     .join(' ')
   const packages = countTopLevel('node_modules')
-  const outDir = existsSync(path.resolve('.pnext', 'dev', 'cache')) ? 'warm' : 'cold'
   return [
     `  runtime          ${typeof Bun !== 'undefined' ? `bun ${Bun.version}` : `node ${process.version}`} · ${platform()} ${arch()} · ${cpus().length} cpus · load ${load}`,
-    `  app              ${packages} node_modules entries · .pnext/dev cache ${outDir}`,
+    `  app              ${packages} node_modules entries · .pnext/dev cache ${cacheAtStart}`,
   ]
 }
 

package/src/cli/build/cache.ts

@@ -0,0 +1,324 @@
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { lstat, mkdir, readFile, readdir, readlink } from 'node:fs/promises'
+import path from 'node:path'
+import type { ResolvedConfig } from '../../config'
+import { frameworkFingerprint } from '../../runtime/fingerprint'
+import type { BuildManifest } from '../../types'
+import { writeFileAtomic } from '../../utils/fs'
+
+const CACHE_VERSION = 2
+const CACHE_SEGMENTS = ['cache', 'build'] as const
+const SKIP_INPUT_DIRS = new Set([
+  '.claude',
+  '.git',
+  '.husky',
+  '.next',
+  '.pnext',
+  '.tmp',
+  '.turbo',
+  '.vercel',
+  '.vscode',
+  'node_modules',
+])
+const SKIP_INPUT_FILE = /(?:^\.DS_Store$|\.(?:log|pid)$)/i
+const LOCK_FILES = [
+  'bun.lock',
+  'bun.lockb',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+]
+
+type InputRecord = [mtimeMs: number, size: number, hash: string]
+
+interface CacheRecord {
+  version: number
+  key: string
+  inputs: Record<string, InputRecord>
+  outputHash: string
+  outputs: Record<string, string>
+}
+
+export interface BuildCacheOptions {
+  adapter?: 'vercel'
+  debugBuildPaths?: string
+  buildMode?: 'compile' | 'generate'
+  debugPrerender?: boolean
+}
+
+export interface BuildCacheSession {
+  enabled: boolean
+  context?: string
+  inputs?: Record<string, InputRecord>
+  manifest?: BuildManifest
+  reason?: string
+}
+
+/** Validate the standard production build before its output directory is touched. */
+export async function lookupBuildCache(
+  config: ResolvedConfig,
+  options: BuildCacheOptions,
+): Promise<BuildCacheSession> {
+  if (!cacheEnabled(options)) return { enabled: false }
+  const record = await readRecord(config.outPath)
+  const inputs = await inputRecords(config, record?.inputs)
+  const context = buildContext()
+  const key = buildKey(context, inputs)
+  if (record?.key !== key) return { enabled: true, context, inputs, reason: 'inputs' }
+  const output = await outputSnapshot(config.outPath)
+  if (output.hash !== record.outputHash) {
+    const changed = changedFiles(record.outputs, output.files).slice(0, 3).join(', ')
+    return { enabled: true, context, inputs, reason: `output (${changed || 'unknown'})` }
+  }
+  try {
+    const manifest = JSON.parse(
+      await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
+    ) as BuildManifest
+    return { enabled: true, context, inputs, manifest, reason: 'hit' }
+  } catch {
+    return { enabled: true, context, inputs, reason: 'manifest' }
+  }
+}
+
+/** Publish a successful build only after every production artifact has landed. */
+export async function writeBuildCache(
+  config: ResolvedConfig,
+  options: BuildCacheOptions,
+  session: BuildCacheSession,
+) {
+  if (!session.enabled || !session.context || !cacheEnabled(options)) return
+  const inputs = await inputRecords(config, session.inputs)
+  const output = await outputSnapshot(config.outPath)
+  const record: CacheRecord = {
+    version: CACHE_VERSION,
+    key: buildKey(session.context, inputs),
+    inputs,
+    outputHash: output.hash,
+    outputs: output.files,
+  }
+  await mkdir(cacheDir(config.outPath), { recursive: true })
+  await writeFileAtomic(recordFile(config.outPath), JSON.stringify(record))
+}
+
+function cacheEnabled(options: BuildCacheOptions) {
+  // Opt-in until the no-change short-circuit is finished: the key currently hashes the whole
+  // environment, so cross-shell hits are rare and the cache adds bookkeeping without payoff.
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (process.env.PNEXT_BUILD_CACHE !== '1') return false
+  return (
+    options.adapter === undefined &&
+    options.debugBuildPaths === undefined &&
+    options.buildMode === undefined &&
+    options.debugPrerender !== true
+  )
+}
+
+function cacheDir(outPath: string) {
+  return path.join(outPath, ...CACHE_SEGMENTS)
+}
+
+function recordFile(outPath: string) {
+  return path.join(cacheDir(outPath), 'result.json')
+}
+
+async function readRecord(outPath: string): Promise<CacheRecord | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(recordFile(outPath), 'utf8')) as CacheRecord
+    if (
+      parsed.version === CACHE_VERSION &&
+      parsed.key &&
+      parsed.inputs &&
+      parsed.outputHash &&
+      parsed.outputs
+    ) {
+      return parsed
+    }
+  } catch {
+    // A partial or older entry is a miss, never a stale hit.
+  }
+  return undefined
+}
+
+function buildContext() {
+  const hash = createHash('sha256')
+  hash.update(`pnext-build-cache:${CACHE_VERSION}\0`)
+  hash.update(frameworkFingerprint())
+  hash.update(`\0bun:${Bun.version}\0`)
+  for (const [name, value] of Object.entries(process.env).sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(`${name}=${value ?? ''}\0`)
+  }
+  return hash.digest('hex')
+}
+
+function buildKey(context: string, inputs: Record<string, InputRecord>) {
+  const hash = createHash('sha256')
+  hash.update(context)
+  for (const [file, record] of Object.entries(inputs).sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(`${file}\0${record[2]}\0`)
+  }
+  return hash.digest('hex')
+}
+
+async function inputRecords(
+  config: ResolvedConfig,
+  previous: Record<string, InputRecord> | undefined,
+) {
+  const files = new Map<string, string>()
+  await collectTree(config.root, 'root', files, config.outPath)
+  await collectModuleGraphInputs(config, files)
+
+  // Dependency trees are represented by package-manager content identities,
+  // while first-party modules above are keyed by their own bytes.
+  for (const [prefix, root] of [
+    ['root-deps', config.root],
+    ['workspace-deps', config.workspaceRoot],
+  ] as const) {
+    for (const name of LOCK_FILES) addFile(files, `${prefix}:${name}`, path.join(root, name))
+    addFile(
+      files,
+      `${prefix}:node_modules/.package-lock.json`,
+      path.join(root, 'node_modules', '.package-lock.json'),
+    )
+  }
+
+  const frameworkRoot = path.resolve(import.meta.dirname, '..', '..')
+  addFile(files, 'framework:package.json', path.join(frameworkRoot, 'package.json'))
+  for (const name of LOCK_FILES) {
+    addFile(files, `framework:${name}`, path.join(frameworkRoot, name))
+    addFile(files, `framework-workspace:${name}`, path.join(frameworkRoot, '..', name))
+  }
+
+  const entries = await Promise.all(
+    [...files].map(async ([key, file]): Promise<[string, InputRecord] | undefined> => {
+      const stats = await lstat(file).catch(() => undefined)
+      if (!stats?.isFile() && !stats?.isSymbolicLink()) return undefined
+      const old = previous?.[key]
+      if (old?.[0] === stats.mtimeMs && old[1] === stats.size) return [key, old]
+      const contents = stats.isSymbolicLink()
+        ? Buffer.from(`link:${await readlink(file)}`)
+        : await readFile(file)
+      return [key, [stats.mtimeMs, stats.size, contentHash(contents)]]
+    }),
+  )
+  return Object.fromEntries(
+    entries.filter((entry): entry is [string, InputRecord] => Boolean(entry)),
+  )
+}
+
+interface ModuleGraphIndex {
+  files?: Record<string, unknown>
+}
+
+async function collectModuleGraphInputs(config: ResolvedConfig, files: Map<string, string>) {
+  let parsed: ModuleGraphIndex
+  try {
+    parsed = JSON.parse(
+      await readFile(path.join(config.outPath, 'cache', 'server', 'graph.json'), 'utf8'),
+    ) as ModuleGraphIndex
+  } catch {
+    return
+  }
+  const frameworkRoot = path.resolve(import.meta.dirname, '..', '..')
+  for (const source of Object.keys(parsed.files ?? {})) {
+    const value = source.slice(2).split('/').join(path.sep)
+    const file = source.startsWith('w:')
+      ? path.resolve(config.workspaceRoot, value)
+      : source.startsWith('f:')
+        ? path.resolve(frameworkRoot, value)
+        : source.startsWith('a:')
+          ? value
+          : undefined
+    if (file) addFile(files, `module:${source}`, file)
+  }
+}
+
+async function collectTree(
+  root: string,
+  prefix: string,
+  files: Map<string, string>,
+  outPath: string,
+  dir = root,
+): Promise<void> {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  await Promise.all(
+    entries.map(async entry => {
+      const file = path.join(dir, entry.name)
+      if (file === outPath || file.startsWith(`${outPath}${path.sep}`)) return
+      if (entry.isDirectory()) {
+        if (!SKIP_INPUT_DIRS.has(entry.name)) await collectTree(root, prefix, files, outPath, file)
+        return
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) return
+      const relative = path.relative(root, file)
+      // Local server logs and top-level response captures are not compiler
+      // inputs; watching processes commonly rewrite them during a build.
+      if (
+        SKIP_INPUT_FILE.test(entry.name) ||
+        (!relative.includes(path.sep) && /\.html?$/i.test(entry.name))
+      ) {
+        return
+      }
+      addFile(files, `${prefix}:${toPosix(relative)}`, file)
+    }),
+  )
+}
+
+function addFile(files: Map<string, string>, key: string, file: string) {
+  if (existsSync(file)) files.set(key, file)
+}
+
+async function outputSnapshot(outPath: string) {
+  const files = new Map<string, string>()
+  const entries = await readdir(outPath, { withFileTypes: true }).catch(() => [])
+  await Promise.all(
+    entries.map(async entry => {
+      if (entry.name === 'cache' || entry.name === 'dev') return
+      const file = path.join(outPath, entry.name)
+      if (entry.isDirectory()) await collectOutputTree(outPath, file, files)
+      else if (entry.isFile() || entry.isSymbolicLink()) {
+        files.set(toPosix(entry.name), file)
+      }
+    }),
+  )
+  const hash = createHash('sha256')
+  const hashes: Record<string, string> = {}
+  for (const [name, file] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    const stats = await lstat(file)
+    const contents = stats.isSymbolicLink()
+      ? Buffer.from(`link:${await readlink(file)}`)
+      : await readFile(file)
+    const contentsHash = contentHash(contents)
+    hashes[name] = contentsHash
+    hash.update(`${name}\0${contentsHash}\0`)
+  }
+  return { hash: hash.digest('hex'), files: hashes }
+}
+
+function changedFiles(before: Record<string, string>, after: Record<string, string>) {
+  return [...new Set([...Object.keys(before), ...Object.keys(after)])].filter(
+    file => before[file] !== after[file],
+  )
+}
+
+async function collectOutputTree(root: string, dir: string, files: Map<string, string>) {
+  const entries = await readdir(dir, { withFileTypes: true })
+  await Promise.all(
+    entries.map(async entry => {
+      const file = path.join(dir, entry.name)
+      if (entry.isDirectory()) await collectOutputTree(root, file, files)
+      else if (entry.isFile() || entry.isSymbolicLink()) {
+        files.set(toPosix(path.relative(root, file)), file)
+      }
+    }),
+  )
+}
+
+function contentHash(contents: Uint8Array) {
+  return createHash('sha256').update(contents).digest('hex')
+}
+
+function toPosix(file: string) {
+  return path.sep === '/' ? file : file.split(path.sep).join('/')
+}

package/src/cli/build.ts

@@ -30,6 +30,7 @@ import {
   buildGlobalCss,
   buildNotFoundCss,
   buildRouteCss,
+  emittedAssetNames,
   prepareRouteCssChunks,
   registerCssRuntime,
   warmCssPipeline,
@@ -76,12 +77,14 @@ import { findProxyFile, proxyExternalLoadTarget, validateProxyFiles } from '../r
 import { setRequestRuntime } from '../routing/request-environment'
 import {
   addClientEntryReason,
+  assertNoServerActionsWithoutCompat,
   findLayouts,
   materializeRouteFacts,
   scanRoutes,
 } from '../routing/routes'
 import { interceptionMarkerLevels } from '../routing/slots'
 import { writeTypegen } from './typegen'
+import { lookupBuildCache, writeBuildCache } from './build/cache'
 import { createVerboseLogger, type VerboseLogger } from '../utils/verbose'
 import { bold, cyan, dim, green } from '../utils/ansi'
 import type {
@@ -177,9 +180,7 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
     `${cyan('▲')} ${bold('pnext')} ${dim('— Creating an optimized production build ...\n')}`,
   )
   const config = await loadConfig(root)
-  // Load Tailwind on the CSS worker while the steps below run, so the first
-  // stylesheet doesn't pay its cold boot.
-  warmCssPipeline(config)
+  const buildCache = lookupBuildCache(config, options)
   // Compat plugin loader: the single gated seam that populates the core
   // extension registries when compat is enabled (no-op for pure-core apps).
   // A build compiles immediately, so it takes both tiers up front.
@@ -190,6 +191,21 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   // server-boot-only hooks out of the build - Next never runs register() during `next build`, so
   // build prerenders must see a noop tracer.
   runInitHooks(config, { build: true })
+  const cached = await buildCache
+  log.log(`build cache ${cached.reason ?? 'disabled'}`)
+  if (cached.manifest) {
+    printBuildSummary(
+      config,
+      cached.manifest.routes,
+      cached.manifest.staticFiles ?? {},
+      performance.now() - startedAt,
+      Boolean(cached.manifest.proxyModule),
+    )
+    return cached.manifest
+  }
+  // Load Tailwind on the CSS worker while the steps below run, so the first
+  // stylesheet doesn't pay its cold boot.
+  warmCssPipeline(config)
   // The vercel adapter's warm pass runs in its own process; start it here so
   // its boot overlaps the build and only the warming itself lands on the
   // adapter step.
@@ -270,6 +286,9 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
     // eslint-disable-next-line @typescript-eslint/require-await
     async () => materializeRouteFacts(routes, route => clientSources.warmRoutes([route])),
   )
+  // Before anything renders: core cannot dispatch a server action, so an app with
+  // one fails the build by name instead of shipping forms that go nowhere.
+  assertNoServerActionsWithoutCompat(routes, nextCompatEnabled(config), config.root)
   // Render-time extensions read the route table from the request runtime (e.g.
   // compat's static-sibling route state); publish it for the prerender pass the
   // same way the serve handlers do.
@@ -358,19 +377,6 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
       (route.client || route.clientReferences.length > 0 || route.needsRouterEntry),
   )
   for (const route of clientRoutes) route.clientEntry = `assets/${clientEntryName(route)}.js`
-  // A prerenderable 404 boots the server graph; the client bundles are esbuild.
-  // Both need only the stub set and the entry names decided just above, so run
-  // them side by side instead of paying the render after the bundle. Result is
-  // consumed after the prerender pass, where it always was.
-  const notFoundDocuments = renderNotFoundDocuments({
-    config,
-    log,
-    skip: options.buildMode === 'compile',
-    documentCss,
-    staticMetadataFiles,
-    staticModuleMetadata,
-  })
-  notFoundDocuments.catch(() => undefined)
   const clientBundles = log.step(
     `client bundles (${clientRoutes.length} route${clientRoutes.length === 1 ? '' : 's'})`,
     () =>
@@ -384,6 +390,21 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
       }),
   )
   clientBundles.catch(() => undefined)
+  // The 404 document links the same content-hashed entries and stylesheets every
+  // other document does, and those names are only final once the client stage has
+  // fingerprinted them — so this render follows the bundle rather than racing it.
+  // Result is consumed after the prerender pass, where it always was.
+  const notFoundDocuments = clientBundles.then(() =>
+    renderNotFoundDocuments({
+      config,
+      log,
+      skip: options.buildMode === 'compile',
+      documentCss,
+      staticMetadataFiles,
+      staticModuleMetadata,
+    }),
+  )
+  notFoundDocuments.catch(() => undefined)
   // The manifest-writing steps and typegen depend on nothing the client stage produces, so they run
   // under it instead of ahead of it. Awaited first so a step failure still reports before a
   // bundling error.
@@ -698,7 +719,6 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
                           ...(route.usesRequest ? { request: new Request(url) } : {}),
                           staticMetadataFiles,
                           staticModuleMetadata,
-                          resolveDynamicMetadataRoutes: true,
                         }),
                       ),
                     ),
@@ -881,6 +901,9 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
     outDir: config.outPath,
     routes,
     staticFiles,
+    // The serving process re-publishes these so a render resolves the same
+    // content-hashed names the build emitted.
+    assetNames: emittedAssetNames(config.outPath),
     staticMetadataFiles,
     ...(Object.keys(staticModuleMetadata).length > 0 ? { staticModuleMetadata } : {}),
     ...(!config.compat?.next
@@ -908,6 +931,8 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   // (typecheck) are awaited next and reported on their own lines.
   const buildDurationMs = performance.now() - startedAt
   const phases = await settleBuildParallelPhases()
+  flushDevModuleCaches()
+  await writeBuildCache(config, options, cached)
 
   printBuildSummary(
     config,
@@ -2156,7 +2181,6 @@ async function renderNotFoundDocuments({
       url: new URL('http://pnext.local/_not-found'),
       staticMetadataFiles,
       staticModuleMetadata,
-      resolveDynamicMetadataRoutes: true,
     })
     return response.text()
   }