@wular/pnext 0.0.18 → 0.0.20

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.18",
+  "version": "0.0.20",
   "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.ts

@@ -30,6 +30,7 @@ import {
   buildGlobalCss,
   buildNotFoundCss,
   buildRouteCss,
+  emittedAssetNames,
   prepareRouteCssChunks,
   registerCssRuntime,
   warmCssPipeline,
@@ -76,6 +77,7 @@ import { findProxyFile, proxyExternalLoadTarget, validateProxyFiles } from '../r
 import { setRequestRuntime } from '../routing/request-environment'
 import {
   addClientEntryReason,
+  assertNoServerActionsWithoutCompat,
   findLayouts,
   materializeRouteFacts,
   scanRoutes,
@@ -270,6 +272,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 +363,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 +376,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 +705,6 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
                           ...(route.usesRequest ? { request: new Request(url) } : {}),
                           staticMetadataFiles,
                           staticModuleMetadata,
-                          resolveDynamicMetadataRoutes: true,
                         }),
                       ),
                     ),
@@ -881,6 +887,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
@@ -2156,7 +2165,6 @@ async function renderNotFoundDocuments({
       url: new URL('http://pnext.local/_not-found'),
       staticMetadataFiles,
       staticModuleMetadata,
-      resolveDynamicMetadataRoutes: true,
     })
     return response.text()
   }

package/src/cli/dev.ts

@@ -1,3 +1,5 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
 import { dim } from '../utils/ansi'
 import { moduleGenerationStats } from '../runtime/module-generations'
 import { markBoot, printBootTrace } from './boot/trace'
@@ -40,6 +42,7 @@ export async function dev(options: DevOptions = {}) {
   markBoot('dev:imports')
   const config = await loadConfig(options.root, { dev: true })
   markBoot('dev:config')
+  warnDuplicateSass(config.root, Boolean(config.compat?.next))
   const port = options.port ?? 3000
   const hostname = options.hostname ?? 'localhost'
   // A memory-triggered restart can briefly race the previous listener's
@@ -76,6 +79,26 @@ export async function dev(options: DevOptions = {}) {
   return server
 }
 
+/** Next's dev-only preflight warning for projects carrying both Sass implementations. */
+function warnDuplicateSass(root: string, nextCompat: boolean): void {
+  if (!nextCompat) return
+  const appRequire = createRequire(path.join(root, 'package.json'))
+  const installed = (name: string) => {
+    try {
+      appRequire.resolve(name)
+      return true
+    } catch {
+      return false
+    }
+  }
+  if (!installed('sass') || !installed('node-sass')) return
+  console.warn(
+    'Your project has both `sass` and `node-sass` installed as dependencies, but should only use one or the other. ' +
+      'Please remove the `node-sass` dependency from your project. ' +
+      ' Read more: https://nextjs.org/docs/messages/duplicate-sass',
+  )
+}
+
 // Every dev reload imports changed modules under fresh URLs, and the ES module
 // registry never evicts, so a long session pins every stale graph in memory.
 // Once RSS crosses the limit, trade a seconds-long restart (vendor bundles are

package/src/cli/migrate/report.ts

@@ -25,7 +25,7 @@ export interface ReportItem {
 export interface MigrationResult {
   edits: Edit[]
   reports: ReportItem[]
-  /** Files reading cookies()/headers()/draftMode() synchronously (Next 14 style). */
+  /** Files reading cookies()/headers()/draftMode() or params/searchParams synchronously (Next 14 style). */
   syncRequestApis: string[]
   /** Files importing next/font/google, which needs the `next-font` metadata package. */
   googleFontImports: string[]

package/src/cli/migrate/run.ts

@@ -66,7 +66,7 @@ async function createPnextConfig(root: string, result: MigrationResult, dryRun:
       legacy
         ? 'export default {\n' +
             '  compat: {\n' +
-            '    // Sync cookies()/headers() still work; migrate to `await` and drop this.\n' +
+            '    // Sync cookies()/headers()/params still work; migrate to `await` and drop this.\n' +
             '    next: { legacyRequestAPIs: true },\n' +
             '  },\n' +
             '};\n'
@@ -84,7 +84,7 @@ async function createPnextConfig(root: string, result: MigrationResult, dryRun:
 
 function reportSyncRequestApis(result: MigrationResult, existingConfig?: string) {
   result.reports.push({
-    title: 'Sync cookies()/headers() detected',
+    title: 'Sync cookies()/headers()/params detected',
     detail: existingConfig
       ? `Set compat: { next: { legacyRequestAPIs: true } } in ${existingConfig} to keep these working, then migrate to \`await\` and remove it. See https://pnext.dev/docs/compat`
       : 'Enabled compat.next.legacyRequestAPIs; migrate to `await` and remove it. See https://pnext.dev/docs/compat',

package/src/cli/migrate/scan.ts

@@ -23,6 +23,15 @@ const NEXT_HEADERS_IMPORT = /import\s*\{([^}]*)\}\s*from\s*['"]next\/headers['"]
 const REQUEST_APIS = new Set(['cookies', 'headers', 'draftMode'])
 const PROMISE_METHODS = new Set(['then', 'catch', 'finally'])
 const SPECIAL_PAGES = ['_app', '_document', '_error']
+// App-router segment files, the only place `params`/`searchParams` arrive as props.
+const SEGMENT_FILES = new Set(['page', 'layout', 'route', 'template', 'default'])
+// Every head whose match ENDS at the parameter list's `(` — default exports and generateMetadata.
+const SEGMENT_HEADS =
+  /export\s+default\s+(?:async\s+)?function\s*[\w$]*\s*\(|export\s+default\s+(?:async\s+)?\(|export\s+(?:async\s+)?function\s+generateMetadata\s*\(|export\s+const\s+generateMetadata\s*(?::[^=]*)?=\s*(?:async\s*)?\(/g
+// Route-handler methods take `{ params }` as their SECOND parameter (the context object).
+const ROUTE_HANDLER_HEADS =
+  /export\s+(?:async\s+)?function\s+(?:GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)\s*\(|export\s+const\s+(?:GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)\s*(?::[^=]*)?=\s*(?:async\s*)?\(/g
+const SYNC_PROPS = ['params', 'searchParams'] as const
 
 export async function scanSources(root: string, result: MigrationResult) {
   const { SHIMMED_NEXT_DIST_PATHS } = await import('../../compat/aliases')
@@ -57,7 +66,9 @@ export async function scanSources(root: string, result: MigrationResult) {
       // package, so only it earns the dependency.
       if (specifier === 'next/font/google') result.googleFontImports.push(relative)
     }
-    if (readsRequestApiSynchronously(text)) result.syncRequestApis.push(relative)
+    if (readsRequestApiSynchronously(text) || readsSyncSegmentProps(file, text)) {
+      result.syncRequestApis.push(relative)
+    }
   }
 
   if (deepImports.length > 0) {
@@ -111,6 +122,122 @@ function readsRequestApiSynchronously(text: string): boolean {
   return false
 }
 
+/**
+ * A segment file whose default export (or generateMetadata) takes `params`/`searchParams` the Next 14
+ * way — annotated as a plain object rather than a Promise, or destructured and read without `await`.
+ * Precision over recall: an unresolvable annotation, an awaited read, or a `params` key anywhere other
+ * than the parameter list (an axios `{ params: { page } }` option bag) never counts.
+ */
+export function readsSyncSegmentProps(file: string, text: string): boolean {
+  const extension = path.extname(file)
+  if (!SEGMENT_FILES.has(path.basename(file, extension))) return false
+  return readsHeadProps(text, SEGMENT_HEADS, 0) || readsHeadProps(text, ROUTE_HANDLER_HEADS, 1)
+}
+
+function readsHeadProps(text: string, heads: RegExp, index: number): boolean {
+  for (const head of text.matchAll(heads)) {
+    const list = balanced(text, head.index + head[0].length - 1, '(', ')')
+    const parameter = (splitTopLevel(list)[index] ?? '').trim()
+    if (parameter && readsPropsSynchronously(parameter, text)) return true
+  }
+  return false
+}
+
+function readsPropsSynchronously(parameter: string, text: string): boolean {
+  const colon = topLevelIndex(parameter, ':')
+  const binding = (colon < 0 ? parameter : parameter.slice(0, colon)).trim()
+  const annotation = colon < 0 ? '' : parameter.slice(colon + 1).trim()
+  const destructured = binding.startsWith('{') ? destructuredKeys(binding) : null
+  for (const prop of SYNC_PROPS) {
+    if (destructured && !destructured.has(prop)) continue
+    if (annotation) {
+      const declared = propertyType(annotation, text, prop)
+      if (declared && !/^Promise\s*</.test(declared)) return true
+      continue
+    }
+    // Untyped JS: a destructured binding read without `await`, or `props.params` read without one.
+    if (destructured) {
+      if (!new RegExp(`await\\s+${prop}\\b`).test(text)) return true
+    } else if (/^[\w$]+$/.test(binding)) {
+      const reads = text.matchAll(new RegExp(`(await\\s+)?\\b${binding}\\.${prop}\\b`, 'g'))
+      if ([...reads].some(read => !read[1])) return true
+    }
+  }
+  return false
+}
+
+/** The declared type of `prop` inside an inline object annotation or a locally declared type/interface. */
+function propertyType(annotation: string, text: string, prop: string): string | undefined {
+  let body: string | undefined
+  if (annotation.startsWith('{')) {
+    body = balanced(annotation, 0, '{', '}')
+  } else {
+    const name = /^[\w$]+/.exec(annotation)?.[0]
+    body = name ? localTypeBody(name, text) : undefined
+  }
+  if (!body) return undefined
+  return new RegExp(`(?:^|[{;,\\n])\\s*${prop}\\s*\\??\\s*:\\s*([^;,\\n]+)`).exec(body)?.[1]?.trim()
+}
+
+function localTypeBody(name: string, text: string): string | undefined {
+  const declaration = new RegExp(`\\b(?:type|interface)\\s+${name}\\b`).exec(text)
+  if (!declaration) return undefined
+  const open = text.indexOf('{', declaration.index)
+  // An alias to something else (`type Props = PageProps<'/x'>`) has no object body of its own.
+  if (open < 0 || /[;)]/.test(text.slice(declaration.index, open))) return undefined
+  return balanced(text, open, '{', '}')
+}
+
+/** The keys of a destructuring pattern, renames included (`{ params: p }` → `params`). */
+function destructuredKeys(binding: string): Set<string> {
+  const keys = new Set<string>()
+  for (const part of splitTopLevel(balanced(binding, 0, '{', '}'))) {
+    const key = /^\s*(?:\.\.\.)?([\w$]+)/.exec(part)?.[1]
+    if (key) keys.add(key)
+  }
+  return keys
+}
+
+/** Text between `open` at `from` and its matching close, exclusive. */
+function balanced(text: string, from: number, open: string, close: string): string {
+  let depth = 0
+  for (let i = from; i < text.length; i++) {
+    if (text[i] === open) depth++
+    else if (text[i] === close && --depth === 0) return text.slice(from + 1, i)
+  }
+  return ''
+}
+
+function splitTopLevel(list: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < list.length; i++) {
+    const char = list[i]!
+    if (char === '=' && list[i + 1] === '>') i++
+    else if ('({[<'.includes(char)) depth++
+    else if (')}]>'.includes(char)) depth--
+    else if (char === ',' && depth === 0) {
+      parts.push(list.slice(start, i))
+      start = i + 1
+    }
+  }
+  parts.push(list.slice(start))
+  return parts
+}
+
+/** Index of `char` outside any bracket pair, or -1. */
+function topLevelIndex(text: string, char: string): number {
+  let depth = 0
+  for (let i = 0; i < text.length; i++) {
+    const current = text[i]!
+    if ('({[<'.includes(current)) depth++
+    else if (')}]>'.includes(current)) depth--
+    else if (current === char && depth === 0) return i
+  }
+  return -1
+}
+
 function scanSpecialPages(root: string, result: MigrationResult) {
   const found: string[] = []
   for (const base of ['pages', path.join('src', 'pages')]) {

package/src/cli/serve/pipeline.ts

@@ -32,7 +32,7 @@ import {
   malformedUrlResponse,
   trailingSlashRedirect,
 } from '../../routing/href'
-import { withForwardedHeaders } from '../../routing/forwarded'
+import { type PeerAddressSource, withForwardedHeaders } from '../../routing/forwarded'
 import { normalizePathname, parseNavState, selectRouteForRequest } from '../../routing/routes'
 import { runWithCacheScope } from '../../request/cache'
 import { metadataRouteHandlerModule } from '../../routing/metadata-files'
@@ -57,6 +57,7 @@ import {
 } from '../../request/context'
 import { setRequestRuntime } from '../../routing/request-environment'
 import { getRenderSpanExtensions } from '../../render/hooks'
+import { publishEmittedAssets } from '../../css/build'
 import { contentType } from '../../utils/content-type'
 import { stopEsbuildService } from '../../utils/esbuild'
 import { markErrorLogged } from '../../utils/error-log'
@@ -107,6 +108,9 @@ export async function createRequestHandler(
   // so runtime renders observe force-cache / revalidate TTLs / tags exactly
   // like build prerenders. No-op for pure-core apps.
   runInitHooks(config)
+  // Content-hashed asset names, as the build emitted them: a render in THIS
+  // process must link the same files, not the logical `global.css` spelling.
+  publishEmittedAssets(config.outPath, manifest.assetNames)
   // Publish the live routing state the compat request interceptors (action
   // dispatch, rewrites) read; prod loads the route table once.
   setRequestRuntime({ config, routes: manifest.routes, dev: false })
@@ -266,13 +270,13 @@ export async function createRequestHandler(
   // resident esbuild service child (~10+ MB RSS) — it respawns if ever needed.
   stopEsbuildService()
 
-  return function handleRequest(request: Request): Promise<Response> {
+  return function handleRequest(request: Request, server?: PeerAddressSource): Promise<Response> {
     // One work unit spans the whole request; its after-queue flushes once the
     // response fully closes (stream end, redirect, notFound, error, abort).
     return runWithWorkUnit('render', async () => {
       const unit = getWorkUnit()
       try {
-        const raw = await handle(request)
+        const raw = await handle(request, server)
         const finalized = await finalizeResponse(
           raw,
           { method: request.method, url: new URL(request.url), headers: request.headers },
@@ -304,10 +308,10 @@ export async function createRequestHandler(
     })
   }
 
-  async function handle(request: Request): Promise<Response> {
+  async function handle(request: Request, server?: PeerAddressSource): Promise<Response> {
     const badRequest = malformedUrlResponse(request)
     if (badRequest) return badRequest
-    request = withForwardedHeaders(request)
+    request = withForwardedHeaders(request, server)
     const requestedUrl = new URL(request.url)
     // assetPrefix is independent from basePath. Strip a path-style asset
     // prefix first so `/cdn/_next/static/*` remains servable even when the app
@@ -502,6 +506,18 @@ export async function createRequestHandler(
             ? { revalidateSeconds: servedBuilt.metadata.revalidateSeconds }
             : undefined,
         )
+        // A prebuilt DOCUMENT's cache-control belongs to the response finalizer,
+        // which owns the one rule (Next's static / ISR / dynamic values) for
+        // rendered and prebuilt pages alike. maybeBuiltFile's `no-cache` is its
+        // asset default, not a claim; a build-captured header is a claim and stays.
+        if (
+          isHtmlResponse(staticFile) &&
+          !(servedBuilt.metadata?.headers ?? []).some(
+            ([key]) => key.toLowerCase() === 'cache-control',
+          )
+        ) {
+          staticFile.headers.delete('cache-control')
+        }
         if (servedBuilt.metadata) {
           const servedTtl = servedBuilt.metadata.revalidateSeconds
           const expired =
@@ -523,11 +539,14 @@ export async function createRequestHandler(
       }
     }
     if (url.pathname.startsWith('/_next/static/') && !built) {
-      setWorkUnitRoute('static-asset', 'static')
+      setWorkUnitRoute('static-asset')
       return applyProxyResponse(
         new Response('Not Found', {
           status: 404,
-          headers: { 'content-type': 'text/plain' },
+          headers: {
+            'cache-control': 'private, no-cache, no-store, max-age=0, must-revalidate',
+            'content-type': 'text/plain;charset=utf-8',
+          },
         }),
         proxyResponse,
       )
@@ -537,20 +556,7 @@ export async function createRequestHandler(
 
     const matched = selection
     if (!matched) {
-      return applyProxyResponse(
-        compressResponse(
-          await renderGlobalNotFoundResponse({
-            config,
-            url,
-            request: canonicalRequest,
-            staticMetadataFiles: manifest.staticMetadataFiles,
-            staticModuleMetadata: manifest.staticModuleMetadata,
-            staticRouteMetadata: manifest.staticRouteMetadata,
-          }),
-          request,
-        ),
-        proxyResponse,
-      )
+      return applyProxyResponse(await renderNotFound(canonicalRequest), proxyResponse)
     }
     if (matched.route.kind === 'handler') {
       setWorkUnitRoute(
@@ -648,20 +654,7 @@ export async function createRequestHandler(
     // prerendered param set; anything else is a 404. (Prebuilt paths were
     // already served from the static output above.)
     if (!dynamicParamsAllowed(matched.route, matched.params)) {
-      return applyProxyResponse(
-        compressResponse(
-          await renderGlobalNotFoundResponse({
-            config,
-            url,
-            request: canonicalRequest,
-            staticMetadataFiles: manifest.staticMetadataFiles,
-            staticModuleMetadata: manifest.staticModuleMetadata,
-            staticRouteMetadata: manifest.staticRouteMetadata,
-          }),
-          request,
-        ),
-        proxyResponse,
-      )
+      return applyProxyResponse(await renderNotFound(canonicalRequest), proxyResponse)
     }
 
     // force-static routes render with an empty request and no search params
@@ -1324,14 +1317,21 @@ function cachedGzip(key: string, body: Buffer) {
 
 export const immutableCacheControl = 'public, max-age=31536000, immutable'
 
-// Chunk and font filenames are content-hashed, so their bytes can never change under a given URL;
-// entries, css and html keep stable names and must revalidate (no-cache still allows storing, so
-// every revisit is a cheap 304). Compat-registered static-asset prefixes are content-hashed the same
-// way, so they qualify too.
+/**
+ * Everything the build emits under `assets/` (served at `/_next/static/*` in
+ * compat) is immutable, which is the promise Next makes for that whole
+ * namespace. It holds because every one of those names carries a content hash:
+ * esbuild's for chunks and fonts, assetContentHash for the route entries and the
+ * stylesheets (see fingerprintClientEntries / fingerprintAsset), and a build id
+ * for `_next/static/<id>/_*Manifest.js`. An UNHASHED name must never reach here —
+ * the same URL would answer different bytes after a deploy, and every browser
+ * that saw the old ones would keep them for a year.
+ *
+ * Route outputs (prerendered html, handler bodies) live outside both prefixes
+ * and stay revalidating; the public/ tree the app ships is likewise untouched.
+ */
 export function immutableAssetPath(relativePath: string) {
-  if (relativePath.startsWith('assets/chunks/') || relativePath.startsWith('assets/fonts/')) {
-    return true
-  }
+  if (relativePath.startsWith('assets/') || relativePath.startsWith('_next/static/')) return true
   return getAssetExtensions()
     .staticAssetPublicPrefixes()
     .some(prefix => relativePath.startsWith(prefix.replace(/^\/+/, '')))