@wular/pnext 0.1.6 → 0.1.8

package/src/routing/proxy.ts

@@ -1,13 +1,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
-// Lazy: the oxc-parser native binding costs ~12.6 MB RSS; load it only when a parse happens.
-const parseSync: typeof import('oxc-parser').parseSync = (...args) =>
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  loadNative(() => require('oxc-parser') as typeof import('oxc-parser')).parseSync(...args)
-import { loadNative } from '../utils/native-require'
-import { registerServerRuntime } from '../runtime/loader'
 import { pathToFileHref, type ResolvedConfig } from '../config'
-import { devServerModuleHref } from '../runtime/modules'
+import { devServerModuleHref, registerServerRuntime } from '../runtime/load'
 import { runWithRequest } from '../request/context'
 import {
   copyMiddlewareHeaders,
@@ -140,14 +134,20 @@ export interface ProxyRunnerOptions {
    * load the build-time bundle that has aliases baked in.
    */
   compiledModuleHref?: string
+  /** A production release's proxy: its source and literal matcher config, as the build found them. */
+  released?: { file?: string; config?: ProxyConfig }
 }
 
 export function createProxyRunner(
   config: ResolvedConfig,
   runnerOptions: ProxyRunnerOptions = {},
 ): ProxyRunner {
-  const file = findProxyFile(config)
-  registerServerRuntime(config, file ? [file] : [])
+  const { released } = runnerOptions
+  const file = released ? released.file : findProxyFile(config)
+  const releasedMatchers = released?.config ? proxyMatchers(released.config) : undefined
+  // Awaited before the proxy module loads; a failure surfaces there.
+  const runtimeReady = registerServerRuntime(config, file ? [file] : [])
+  runtimeReady.catch(() => undefined)
   let moduleKey: string | undefined
   let modulePromise: Promise<ProxyModule> | undefined
   let matchers: CompiledMatcher[] | undefined
@@ -155,12 +155,14 @@ export function createProxyRunner(
   /** The module for `options`, started at most once per import version. */
   function proxyModule(options: ProxyRunOptions) {
     const key = proxyModuleKey(options)
+    const load = () =>
+      runtimeReady.then(() => importProxyModule(config, file!, options, runnerOptions))
     if (key !== moduleKey) {
       moduleKey = key
-      modulePromise = importProxyModule(config, file!, options, runnerOptions)
+      modulePromise = load()
       matchers = undefined
     }
-    return (modulePromise ??= importProxyModule(config, file!, options, runnerOptions))
+    return (modulePromise ??= load())
   }
 
   const runner: ProxyRunner = async (request, options = {}) => {
@@ -176,7 +178,7 @@ export function createProxyRunner(
     // Matcher first, straight off the source: a request no matcher selects must not wait on the
     // proxy's compile+import, which is otherwise the first serial link of a cold page.
     if (!matchers && proxyMatcherGateEnabled()) {
-      const staticMatchers = staticProxyMatchers(file)
+      const staticMatchers = released ? releasedMatchers : await staticProxyMatchers(file)
       if (staticMatchers && !matchesProxy(staticMatchers, url, request)) return undefined
     }
 
@@ -397,7 +399,7 @@ export function proxyRoutePatterns(config: ProxyConfig | undefined) {
   const matcher = config?.matcher
   if (!matcher) return ['^/(.*)$']
   const matchers = Array.isArray(matcher) ? matcher : [matcher]
-  return matchers.map(item => `^${matcherPattern(matcherSource(item))}$`)
+  return matchers.map(item => anchoredMatcherPattern(matcherSource(item)))
 }
 
 async function importProxyModule(
@@ -440,7 +442,7 @@ const staticMatcherCache = new Map<string, { key: string; matchers?: CompiledMat
  * middleware-manifest.json at build time); anything computed, any parse error, and any file without a
  * literal `config` yields undefined, and the caller falls back to the imported module's config.
  */
-function staticProxyMatchers(file: string): CompiledMatcher[] | undefined {
+async function staticProxyMatchers(file: string): Promise<CompiledMatcher[] | undefined> {
   let key: string
   try {
     const stats = statSync(file)
@@ -452,6 +454,7 @@ function staticProxyMatchers(file: string): CompiledMatcher[] | undefined {
   if (cached?.key === key) return cached.matchers
   let matchers: CompiledMatcher[] | undefined
   try {
+    const { staticProxyConfig } = await import('./proxy-config')
     const config = staticProxyConfig(file, readFileSync(file, 'utf8'))
     if (config) matchers = proxyMatchers(config)
   } catch {
@@ -461,121 +464,6 @@ function staticProxyMatchers(file: string): CompiledMatcher[] | undefined {
   return matchers
 }
 
-function staticProxyConfig(file: string, source: string): ProxyConfig | undefined {
-  const result = parseSync(file, source, { lang: parserLang(file) })
-  // A recovered parse may have dropped the very declaration we are reading.
-  if (result.errors.length > 0) return undefined
-  for (const statement of result.program.body as StaticNode[]) {
-    if (statement.type !== 'ExportNamedDeclaration') continue
-    const declaration = statement.declaration
-    if (declaration?.type !== 'VariableDeclaration') continue
-    for (const declarator of declaration.declarations ?? []) {
-      if (declarator.id?.type !== 'Identifier' || declarator.id.name !== 'config') continue
-      const value = staticValue(declarator.init)
-      return isProxyConfigShape(value) ? (value as ProxyConfig) : undefined
-    }
-  }
-  return undefined
-}
-
-function parserLang(file: string) {
-  const ext = path.extname(file)
-  if (ext === '.tsx') return 'tsx'
-  if (ext === '.jsx') return 'jsx'
-  return ext === '.js' || ext === '.mjs' ? 'js' : 'ts'
-}
-
-/** Structural view of the oxc AST nodes this file reads — no full type import. */
-interface StaticNode {
-  type: string
-  name?: string
-  value?: unknown
-  computed?: boolean
-  shorthand?: boolean
-  key?: StaticNode
-  init?: StaticNode
-  id?: StaticNode
-  declaration?: StaticNode
-  declarations?: StaticNode[]
-  expression?: StaticNode
-  properties?: StaticNode[]
-  elements?: (StaticNode | null)[]
-  expressions?: StaticNode[]
-  quasis?: { value?: { cooked?: string } }[]
-}
-
-/** Literal-only evaluation; `undefined` marks "not statically known". */
-function staticValue(node: StaticNode | undefined | null): unknown {
-  if (!node) return undefined
-  switch (node.type) {
-    // `… as const` / `… satisfies ProxyConfig` wrap the literal, they never change it.
-    case 'TSAsExpression':
-    case 'TSSatisfiesExpression':
-    case 'TSNonNullExpression':
-      return staticValue(node.expression)
-    case 'Literal':
-    case 'StringLiteral':
-    case 'NumericLiteral':
-    case 'BooleanLiteral':
-      // A regex literal reports `value: null` here; it is not a matcher shape.
-      return node.value === null ? undefined : node.value
-    case 'TemplateLiteral':
-      return node.expressions?.length === 0
-        ? (node.quasis?.[0]?.value?.cooked ?? undefined)
-        : undefined
-    case 'ArrayExpression': {
-      const items: unknown[] = []
-      for (const element of node.elements ?? []) {
-        const value = staticValue(element)
-        if (value === undefined) return undefined
-        items.push(value)
-      }
-      return items
-    }
-    case 'ObjectExpression': {
-      const object: Record<string, unknown> = {}
-      for (const property of node.properties ?? []) {
-        if (property.type !== 'Property' && property.type !== 'ObjectProperty') return undefined
-        if (property.computed) return undefined
-        const key =
-          property.key?.type === 'Identifier' ? property.key.name : (property.key?.value as string)
-        if (typeof key !== 'string') return undefined
-        const value = staticValue(property.value as StaticNode | undefined)
-        if (value === undefined) return undefined
-        object[key] = value
-      }
-      return object
-    }
-    default:
-      return undefined
-  }
-}
-
-/** Only a config whose `matcher` is exactly the documented shape may gate. */
-function isProxyConfigShape(value: unknown): boolean {
-  if (typeof value !== 'object' || value === null) return false
-  const matcher = (value as { matcher?: unknown }).matcher
-  if (matcher === undefined) return true
-  const items = Array.isArray(matcher) ? matcher : [matcher]
-  return items.every(item => {
-    if (typeof item === 'string') return true
-    if (typeof item !== 'object' || item === null) return false
-    const { source, has, missing } = item as Record<string, unknown>
-    if (typeof source !== 'string') return false
-    return [has, missing].every(
-      list => list === undefined || (Array.isArray(list) && list.every(isConditionShape)),
-    )
-  })
-}
-
-function isConditionShape(value: unknown): boolean {
-  if (typeof value !== 'object' || value === null) return false
-  const { type, key, value: expected } = value as Record<string, unknown>
-  if (type !== 'header' && type !== 'query' && type !== 'cookie' && type !== 'host') return false
-  if (key !== undefined && typeof key !== 'string') return false
-  return expected === undefined || typeof expected === 'string'
-}
-
 function proxyMatchers(config: ProxyConfig | undefined): CompiledMatcher[] {
   const matcher = config?.matcher
   if (!matcher) return [{ regex: /.*/ }]
@@ -588,10 +476,11 @@ function proxyMatchers(config: ProxyConfig | undefined): CompiledMatcher[] {
 }
 
 function matchesProxy(matchers: CompiledMatcher[], url: URL, request: Request) {
-  const decoded = decodePathSeparators(url.pathname)
+  const { pathname } = url
+  const decoded = pathname.includes('%') ? decodedPathnames(pathname) : []
   return matchers.some(
     matcher =>
-      (matcher.regex.test(url.pathname) || matcher.regex.test(decoded)) &&
+      (matcher.regex.test(pathname) || decoded.some(item => matcher.regex.test(item))) &&
       matchesConditions(matcher, url, request),
   )
 }
@@ -641,8 +530,15 @@ function conditionValue(condition: ProxyRouteCondition, url: URL, request: Reque
   }
 }
 
-function decodePathSeparators(pathname: string) {
-  return pathname.replace(/%2f/gi, '/')
+// Next also matches `decodeURIComponent(pathname)`, so encoded paths can't skip the proxy.
+function decodedPathnames(pathname: string) {
+  const decoded = [pathname.replace(/%2f/gi, '/')]
+  try {
+    decoded.push(decodeURIComponent(pathname))
+  } catch {
+    // Malformed escapes match on the raw forms only.
+  }
+  return decoded
 }
 
 function matcherSource(matcher: ProxyMatcher) {
@@ -650,7 +546,12 @@ function matcherSource(matcher: ProxyMatcher) {
 }
 
 function matcherRegex(matcher: string) {
-  return new RegExp(`^${matcherPattern(matcher)}$`)
+  return new RegExp(anchoredMatcherPattern(matcher))
+}
+
+// Next's path-to-regexp (strict: false) also matches a trailing slash; routing strips any run of them.
+function anchoredMatcherPattern(matcher: string) {
+  return `^(?:${matcherPattern(matcher)})/*$`
 }
 
 function matcherPattern(matcher: string) {

package/src/routing/routes.ts

@@ -1,7 +1,6 @@
 import path from 'node:path'
 import { existsSync } from 'node:fs'
-import { listFiles, listFilesSync, readDirListing, toPosixPath, withDirCache } from '../utils/fs'
-import { safeDecode } from '../utils/decode'
+import { listFiles, listFilesSync, toPosixPath, withDirCache } from '../utils/fs'
 import {
   dynamicCallsFromSource,
   pnextDynamicImportNames,
@@ -11,6 +10,13 @@ import { resolveImport, resolveModuleAlias, resolvePackageSpecifier } from '../r
 import { dynamicCallFacts, scanFacts, type DynamicCallFact } from '../resolve/scan-facts'
 import { readSourceSync } from '../resolve/source-text'
 import { globalCssSourcesForPaths } from '../css/build'
+import {
+  conventionFileName,
+  findConventionFiles,
+  findLayouts,
+  pageExtensions,
+  serverActionsUnsupportedMessage,
+} from './match'
 import {
   childrenDefaultFile,
   interceptionMarkerLevels,
@@ -24,11 +30,9 @@ import type {
   ClientEntryReason,
   MetadataRouteEntry,
   MetadataRouteKind,
-  NavState,
   RouteInterception,
   RouteManifestEntry,
   RouteMode,
-  RouteParamValue,
   RouteSegmentConfig,
 } from '../types'
 import {
@@ -48,20 +52,28 @@ import {
   sourceUsesRegisteredRequestApi,
 } from '../extensions'
 
+export {
+  findConventionFiles,
+  findGlobalError,
+  findLayouts,
+  matchInterception,
+  matchRoute,
+  normalizePathname,
+  parseNavState,
+  selectRouteForRequest,
+  serverActionsUnsupportedMessage,
+  type InterceptionRouteMatch,
+  type RouteRenderSelection,
+} from './match'
+
 // Single source of truth for the page/convention extension list. `.tsx`/`.ts` stay first so an all-.tsx app
 // resolves on the first candidate and produces the identical file as before; .js/.jsx/.mjs are additive
 // alternatives, and compat appends `mdx`/`md` via registerPageExtensions. EVERYTHING below derives from
 // pageExtensions()/routeHandlerExtensions() LAZILY, computed on first use and memoized, so the compat
 // registration that runs at bootstrap - before scanRoutes - is honored; a module-level const regex is baked
 // at import time, which is too early.
-const BASE_PAGE_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js', 'mjs'] as const
 const BASE_ROUTE_HANDLER_EXTENSIONS = ['ts', 'tsx', 'js', 'mjs'] as const
 
-/** Base + compat-registered page extensions, de-duplicated in order. */
-function pageExtensions(): string[] {
-  return [...new Set([...BASE_PAGE_EXTENSIONS, ...extraPageExtensions()])]
-}
-
 /** Route-handler extensions (route.*); compat page extensions do not apply. */
 function routeHandlerExtensions(): readonly string[] {
   return BASE_ROUTE_HANDLER_EXTENSIONS
@@ -79,8 +91,6 @@ function boundaryConventions(): string[] {
   return [...componentConventions, ...extraBoundaryConventionNames()]
 }
 
-const globalErrorBase = 'global-error'
-
 // The extension list is only known after compat bootstrap runs (which may
 // registerPageExtensions), and scanRoutes always runs after bootstrap. Each
 // pattern is computed on first use and memoized so the compat additions land
@@ -153,15 +163,6 @@ function extensionRegex(base: string, extensions: readonly string[]) {
   return new RegExp(`(^|/)${escapeRegex(base)}\\.(${extensions.join('|')})$`)
 }
 
-/** Nearest existing file named `<base>.<ext>` for the convention extensions. */
-function conventionFileName(dir: string, base: string) {
-  const { files } = readDirListing(dir)
-  for (const extension of pageExtensions()) {
-    if (files.has(`${base}.${extension}`)) return path.join(dir, `${base}.${extension}`)
-  }
-  return undefined
-}
-
 interface RouteParts {
   route: string
   pattern: string
@@ -1107,10 +1108,6 @@ function appendDefaultDerivedRoutes(
   }
 }
 
-export function findLayouts(appPath: string, routeFilePath: string) {
-  return findConventionFiles(appPath, routeFilePath, 'layout')
-}
-
 /**
  * CSS imported by the app's ROOT `not-found.*` (and its module graph), in
  * source order, excluding the root-layout global CSS (which is served
@@ -1147,236 +1144,6 @@ export async function collectFileCss(
   return collectCssImports(context, existing)
 }
 
-/**
- * Walk from the route's directory up to `appPath`, returning one convention file per segment ordered
- * root-to-leaf. `name` may be a bare base (`'layout'`) or carry an extension - a known extension is stripped
- * so the full extension list is tried. Each segment resolves to the first existing `<base>.<ext>`; when none
- * exists the `.tsx` candidate is returned so existing callers that filter by `existsSync` keep
- * byte-identical behavior.
- */
-export function findConventionFiles(appPath: string, routeFilePath: string, name: string) {
-  const base = conventionBase(name)
-  const files: string[] = []
-  let dir = path.dirname(routeFilePath)
-
-  while (dir.startsWith(appPath)) {
-    files.push(conventionFileName(dir, base) ?? path.join(dir, `${base}.tsx`))
-    if (dir === appPath) break
-    dir = path.dirname(dir)
-  }
-
-  return files.reverse()
-}
-
-function conventionBase(name: string) {
-  const match = new RegExp(`\\.(${pageExtensions().join('|')})$`).exec(name)
-  return match ? name.slice(0, -match[0].length) : name
-}
-
-/** App-root `global-error.*` file, if present (BuildManifest.globalErrorFile). */
-export function findGlobalError(appPath: string) {
-  return conventionFileName(appPath, globalErrorBase)
-}
-
-export function matchRoute(routes: RouteManifestEntry[], pathname: string) {
-  // Trailing-slash tolerance: '/route/' matches the same entry as '/route'
-  // (Next redirects these away; static file serving already accepts both).
-  const normalized = normalizePathname(pathname)
-  for (const route of routes) {
-    // Interception entries never match a plain (hard) request; they apply
-    // only through matchInterception on soft navigations.
-    if (route.interception) continue
-    const match = routeRegex(route).exec(normalized)
-    if (!match) continue
-    return { route, params: routeMatchParams(route, match) }
-  }
-  return null
-}
-
-export function normalizePathname(pathname: string) {
-  return pathname.length > 1 ? pathname.replace(/\/+$/, '') || '/' : pathname
-}
-
-function routeMatchParams(route: RouteManifestEntry, match: RegExpExecArray) {
-  const params: Record<string, RouteParamValue> = {}
-  route.params.forEach((name, index) => {
-    const decoded = safeDecode(match[index + 1] ?? '')
-    // A runtime request whose segment IS the dynamic placeholder for its own
-    // param (`[slug]`, whether sent raw or as `%5Bslug%5D`) is Next's "params
-    // placeholder": it must surface the ENCODED placeholder (`%5Bslug%5D`), not
-    // a decoded `[slug]`. A decoded `[slug]` reads as a fallback param and would
-    // trigger a fallback-shell render (failing without a parent Suspense
-    // boundary); Next keeps it URL-encoded to render at runtime instead.
-    // Fallback-shell generation injects its placeholder params through a
-    // separate build path, so this only affects live requests.
-    params[name] = decoded === `[${name}]` ? encodeURIComponent(decoded) : decoded
-  })
-  if (route.catchAll) {
-    params[route.catchAll] = (match[route.params.length + 1] ?? '')
-      .split('/')
-      .filter(Boolean)
-      .map(safeDecode)
-  }
-  return params
-}
-
-export interface InterceptionRouteMatch {
-  route: RouteManifestEntry
-  params: Record<string, RouteParamValue>
-}
-
-/**
- * Match a soft navigation against interception entries: the entry's target
- * pattern must match the destination and the navigation must originate at or
- * below the interceptor's base (the children path the current document
- * rendered from). The deepest base wins. A no-op when destination equals the
- * origin (a refresh re-renders whatever produced the current document).
- */
-export function matchInterception(
-  routes: RouteManifestEntry[],
-  pathname: string,
-  fromPath: string | undefined,
-): InterceptionRouteMatch | null {
-  if (!fromPath) return null
-  const target = normalizePathname(pathname)
-  const from = normalizePathname(fromPath)
-  if (target === from) return null
-  let best: InterceptionRouteMatch | null = null
-  let bestDepth = -1
-  for (const route of routes) {
-    const interception = route.interception
-    if (!interception) continue
-    const match = routeRegex(route).exec(target)
-    if (!match) continue
-    const basePattern = interception.basePattern ? `/${interception.basePattern}` : ''
-    if (!new RegExp(`^${basePattern}(?:/.*)?$`).test(from)) continue
-    const depth = interception.base.split('/').filter(Boolean).length
-    if (depth <= bestDepth) continue
-    bestDepth = depth
-    best = { route, params: routeMatchParams(route, match) }
-  }
-  return best
-}
-
-export interface RouteRenderSelection {
-  route: RouteManifestEntry
-  params: Record<string, RouteParamValue>
-  /** Pathname the children tree renders from (normalized). */
-  childrenPath: string
-  /** Internal pathname after rewrites, used to resolve interception slots. */
-  targetPath: string
-}
-
-/**
- * Pick the entry a page request renders. Hard requests match plainly. Soft navigations first consult
- * interception entries; a slot interception (and a synthetic slot URL reached with known origin) renders the
- * ORIGIN's entry as host - the current page stays while the slot content changes - with the children tree
- * anchored at `childrenPath`.
- */
-export function selectRouteForRequest(
-  routes: RouteManifestEntry[],
-  pathname: string,
-  nav?: import('../types').NavState,
-): RouteRenderSelection | null {
-  const target = normalizePathname(pathname)
-  if (nav) {
-    const intercepted = matchInterception(routes, target, nav.children)
-    if (intercepted) {
-      if (!intercepted.route.interception?.slotDir) {
-        return {
-          route: intercepted.route,
-          params: intercepted.params,
-          childrenPath: target,
-          targetPath: target,
-        }
-      }
-      const host = hostMatch(routes, nav.children)
-      if (host) return { ...host, targetPath: target }
-    }
-  }
-  const matched = matchRoute(routes, target)
-  if (!matched) return null
-  if (nav && matched.route.synthetic && nav.children) {
-    const primary = matchRoute(
-      routes.filter(route => !route.synthetic),
-      target,
-    )
-    const syntheticOwner = matched.route.syntheticSlotDir
-      ? path.dirname(matched.route.syntheticSlotDir)
-      : undefined
-    const primaryFromOwner =
-      primary && syntheticOwner ? path.relative(syntheticOwner, primary.route.file) : undefined
-    if (
-      primary &&
-      primaryFromOwner !== undefined &&
-      primaryFromOwner !== '..' &&
-      !primaryFromOwner.startsWith(`..${path.sep}`)
-    ) {
-      return {
-        route: primary.route,
-        params: primary.params,
-        childrenPath: target,
-        targetPath: target,
-      }
-    }
-    const host = hostMatch(routes, nav.children)
-    if (
-      host &&
-      host.route !== matched.route &&
-      matched.route.syntheticSlotDir &&
-      host.route.slotDirs?.includes(matched.route.syntheticSlotDir)
-    ) {
-      return { ...host, targetPath: target }
-    }
-  }
-  return {
-    route: matched.route,
-    params: matched.params,
-    childrenPath: target,
-    targetPath: target,
-  }
-}
-
-/**
- * Navigation headers from the client soft-nav runtime: `x-pnext-soft-nav`
- * marks the fetch and `x-pnext-nav-state` carries the current document's
- * parallel-route state (URI-encoded JSON).
- */
-export function parseNavState(request: Request): NavState | undefined {
-  if (!request.headers.get('x-pnext-soft-nav')) return undefined
-  const raw = request.headers.get('x-pnext-nav-state')
-  if (!raw) return {}
-  try {
-    const parsed = JSON.parse(decodeURIComponent(raw)) as unknown
-    if (parsed && typeof parsed === 'object') return parsed
-  } catch {
-    // Malformed state degrades to a plain soft navigation.
-  }
-  return {}
-}
-
-function hostMatch(
-  routes: RouteManifestEntry[],
-  fromPath: string | undefined,
-): RouteRenderSelection | null {
-  if (!fromPath) return null
-  const from = normalizePathname(fromPath)
-  const host = matchRoute(routes, from)
-  if (host?.route.kind !== 'page') return null
-  return { route: host.route, params: host.params, childrenPath: from, targetPath: from }
-}
-
-const routeRegexCache = new WeakMap<RouteManifestEntry, RegExp>()
-
-function routeRegex(route: RouteManifestEntry) {
-  let regex = routeRegexCache.get(route)
-  if (!regex) {
-    regex = new RegExp(`^${route.pattern}$`)
-    routeRegexCache.set(route, regex)
-  }
-  return regex
-}
-
 interface RouteSegmentToken {
   route: string
   /** Regex piece; absent for the optional catch-all (assembled specially). */
@@ -1784,32 +1551,6 @@ function serverActionFileFact(context: ScanContext, sourceFiles: string[]) {
  * Read once, act once: the file, what pnext will not do, and both remedies. No
  * stack - the CLI prints `error.message` alone (cli/index.ts).
  */
-export function serverActionsUnsupportedMessage(offender: {
-  file: string
-  route?: string
-  root?: string
-}) {
-  const file = offender.root
-    ? toPosixPath(path.relative(offender.root, offender.file))
-    : offender.file
-  const reach = offender.route ? `, reachable from the route ${offender.route}` : ''
-  return [
-    `Server actions need next compat, and this app is pure core.`,
-    ``,
-    `  ${file} has a 'use server' directive${reach}.`,
-    ``,
-    `pnext will not build this app: core has no server-action registry and no`,
-    `dispatch endpoint, so the action could only render as a form that submits`,
-    `nowhere.`,
-    ``,
-    `Fix it one of two ways:`,
-    `  1. Enable compat in pnext.config.ts:`,
-    `       export default { compat: { next: true } }`,
-    `  2. Or delete the 'use server' directive from ${file}, if those exports are`,
-    `     only ever called on the server (in core the directive does nothing).`,
-  ].join('\n')
-}
-
 /**
  * Fail the build / the dev request rather than render a form whose action goes
  * nowhere. Only page routes carry the fact (see serverActionFileFact), so a

package/src/runtime/fingerprint.ts

@@ -7,6 +7,12 @@ import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, type Dir
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+declare const PNEXT_PREBUNDLE: { fingerprint: string } | undefined
+
+// Read off the prebundle's define, not imported: compat compiles this module into app graphs.
+const prebundleFingerprint =
+  typeof PNEXT_PREBUNDLE === 'object' ? PNEXT_PREBUNDLE.fingerprint : undefined
+
 /**
  * Exactly what the package publishes and the vercel adapter ships: source extensions only, never
  * declarations (both drop them) and never machine-local files like `.DS_Store`. The same tree must
@@ -101,6 +107,9 @@ function writeRecord(dir: string, record: Record) {
 }
 
 let fingerprint: string | undefined
+let fingerprintStats: string | undefined
+// Set once this process has hashed the tree's content: only that answer may serve another app.
+let scanned = false
 const recorded = new Set<string>()
 
 /**
@@ -109,24 +118,30 @@ const recorded = new Set<string>()
  *
  * `recordDir` (a cache root) buys the O(1) stat path across restarts; without it the tree is read.
  * `PNEXT_FRAMEWORK_FINGERPRINT` pins the value outright — the bisect seam, and how a deployment can
- * replay its build's generation without walking the tree at all.
+ * replay its build's generation without walking the tree at all. The prebundle pins its publish-time value.
  */
 export function frameworkFingerprint(recordDir?: string) {
   // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const pinned = process.env.PNEXT_FRAMEWORK_FINGERPRINT
+  const pinned = process.env.PNEXT_FRAMEWORK_FINGERPRINT ?? prebundleFingerprint
   if (pinned) return pinned
   // Memoized, but a second app in the same process still gets its own record - without one its next
   // boot pays the full read for a fingerprint this process already knows.
   if (fingerprint !== undefined && (!recordDir || recorded.has(recordDir))) return fingerprint
-  const files = sourceFiles(frameworkSrc)
-  const stats = statSignature(files, frameworkSrc)
   const previous = recordDir ? readRecord(recordDir) : undefined
-  fingerprint =
-    previous?.stats === stats ? previous.fingerprint : contentFingerprint(files, frameworkSrc)
+  // One content scan per process; after it a later record dir only needs its record written. A
+  // stat-only answer from an app's record serves that app, never another app's fresh cache.
+  if (!scanned || fingerprint === undefined || fingerprintStats === undefined) {
+    const files = sourceFiles(frameworkSrc)
+    fingerprintStats = statSignature(files, frameworkSrc)
+    const recordedFingerprint =
+      previous?.stats === fingerprintStats ? previous.fingerprint : undefined
+    scanned = recordedFingerprint === undefined
+    fingerprint = recordedFingerprint ?? contentFingerprint(files, frameworkSrc)
+  }
   if (recordDir) {
     recorded.add(recordDir)
-    if (previous?.stats !== stats)
-      writeRecord(recordDir, { version: RECORD_VERSION, stats, fingerprint })
+    if (previous?.stats !== fingerprintStats)
+      writeRecord(recordDir, { version: RECORD_VERSION, stats: fingerprintStats, fingerprint })
   }
   return fingerprint
 }