@wular/pnext 0.0.9 → 0.0.11

package/src/render/renderer.ts

@@ -106,6 +106,7 @@ import {
 import { captureCacheScope, runWithCacheScope } from '../request/cache'
 import { registerServerRuntime } from '../runtime/loader'
 import { readText } from '../utils/fs'
+import { traceEnabled } from '../utils/trace-flags'
 import {
   flushDevProfileLines,
   formatProfileDuration,
@@ -168,6 +169,7 @@ import {
   type RouteParamsSnapshot,
 } from './island-context'
 import { escapeHtml } from '../utils/html'
+import { internalErrorHtml, isPnextInternalError } from '../dev/internal-error'
 import type {
   Metadata,
   MetadataLink,
@@ -1094,8 +1096,7 @@ interface ProfileRenderOptions {
 }
 
 function renderProfile(options: ProfileRenderOptions): RenderProfile | undefined {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (!process.env.PNEXT_DEV_PROFILE || !options.dev) return undefined
+  if (!traceEnabled('server') || !options.dev) return undefined
   return { label: options.route.route }
 }
 
@@ -2992,6 +2993,23 @@ async function pageRender(options: RenderOptions, stream: boolean): Promise<Page
         },
       )
     }
+    // An error thrown entirely inside pnext's own frames is a framework bug the app cannot fix:
+    // in dev it gets the loud internal-error document (full trace + prefilled GitHub report)
+    // instead of hiding behind the app's error boundaries or the generic global-error page.
+    if (options.dev) {
+      const resolved = resolveThrownError(error, nextCompatEnabled(options.config))
+      if (isPnextInternalError(resolved)) {
+        logDevError(options, resolved)
+        return globalErrorPage(
+          internalErrorHtml({
+            error: resolved,
+            route: options.route.route,
+            url: String(options.url),
+            digest: (resolved as Error & { digest?: string }).digest,
+          }),
+        )
+      }
+    }
     // A nearest error.* boundary catches first (rendered inside the document).
     // Only when no error boundary exists does global-error.* take over the whole
     // document (it supplies its own <html>/<body>); otherwise the normal error

package/src/render/slots.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { basename, join, relative, sep } from 'node:path'
 import { h, type ComponentChildren, type ComponentType } from 'preact'

package/src/request/context.ts

@@ -346,6 +346,21 @@ function dynamicBailoutRoute(): string | undefined {
   return typeof route === 'string' ? route : undefined
 }
 
+/**
+ * compat.next.legacyRequestAPIs — Next 15's transitional sync request APIs. Core owns the boolean cell
+ * (set from loadConfig); compat's cookies()/headers()/draftMode() read it. globalThis-anchored so a
+ * prebundled server entry carrying its own copy of this module sees the same flag.
+ */
+const LEGACY_REQUEST_APIS = Symbol.for('pnext.legacyRequestAPIs')
+
+export function setLegacyRequestAPIs(enabled: boolean): void {
+  ;(globalThis as Record<PropertyKey, unknown>)[LEGACY_REQUEST_APIS] = enabled
+}
+
+export function legacyRequestAPIs(): boolean {
+  return (globalThis as Record<PropertyKey, unknown>)[LEGACY_REQUEST_APIS] === true
+}
+
 export function requireRequest(api: string) {
   const probeRoute = dynamicBailoutRoute()
   if (probeRoute !== undefined) {

package/src/runtime/loader.ts

@@ -44,6 +44,7 @@ import { readNodeModuleBundle, writeNodeModuleBundle } from '../dev/restart/node
 import { setBasePathPrefix, setDefaultPrefetchMode, setTrailingSlashUrls } from '../routing/href'
 import { resolveExternalLoadTarget, resolveImport, workspacePackageRoots } from '../resolve/imports'
 import { escapeRegex } from '../utils/code'
+import { traceEnabled } from '../utils/trace-flags'
 import { writeFileAtomic } from '../utils/fs'
 
 const require = createRequire(import.meta.url)
@@ -302,8 +303,7 @@ function registerResolvePlugin() {
 function registerLoadPlugin(root: string) {
   if (registeredLoadRoots.has(root)) return
   registeredLoadRoots.add(root)
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (process.env.PNEXT_DEBUG_LOADPLUGIN) {
+  if (traceEnabled('server')) {
     console.error(`[loadplugin] register root=${root} extras=${currentLoadExtras().join(',')}`)
   }
   loadPluginExtras.set(root, currentLoadExtras())

package/src/runtime/module-cache.ts

@@ -15,6 +15,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { ResolvedConfig } from '../config'
 import { writeFileAtomic } from '../utils/fs'
+import { traceEnabled } from '../utils/trace-flags'
 
 /**
  * Kill switch for the request-head trims: the naming walk's synchronous source
@@ -224,12 +225,11 @@ function createDevModuleCache(
     .slice(0, 16)
   establishCacheTrust(root)
   const records = indexRecords(readIndexFile(indexFile), key, workspaceRoot)
-  // PNEXT_DEV_CACHE_DEBUG=1 names every source whose hash differs from the one
+  // PNEXT_TRACE=server names every source whose hash differs from the one
   // the last boot persisted — i.e. exactly why an artifact was renamed and
   // recompiled instead of reused.
   const booted =
-    // eslint-disable-next-line turbo/no-undeclared-env-vars
-    process.env.PNEXT_DEV_CACHE_DEBUG && records.size > 0
+    traceEnabled('server') && records.size > 0
       ? new Map([...records].map(([file, record]) => [file, record.srcHash] as const))
       : undefined
   const pending = new Map<string, Promise<SourceRecord>>()
@@ -613,8 +613,15 @@ function markerFile(root: string) {
  */
 function establishCacheTrust(root: string) {
   const current = readMarker(root)
-  const value = current ?? randomUUID()
-  if (!current) {
+  // Generation-qualified: artifacts embed paths shaped by pnext's own compile/vendor source (vendor
+  // keys, emitted import shapes), so a cache written by a different pnext generation must not be
+  // reused - 0.0.9-era modules kept importing vendor artifacts 0.0.10 keyed differently, and every
+  // request through one 500'd until a manual wipe. A mismatched or legacy marker distrusts the
+  // folder; everything recompiles in place.
+  const generation = `${frameworkFingerprint()}:`
+  const trusted = current?.startsWith(generation) ? current : undefined
+  const value = trusted ?? `${generation}${randomUUID()}`
+  if (!trusted) {
     writeMarker(root, value)
     wiped.add(root)
   }

package/src/runtime/modules.ts

@@ -23,6 +23,7 @@ import {
 } from './loader'
 import { externalServerPackageHref, runtimeServerImportTarget } from '../runtime/vendor-build'
 import { writeFileAtomic } from '../utils/fs'
+import { traceEnabled, traceValue } from '../utils/trace-flags'
 import { createHash } from 'node:crypto'
 import {
   extraLoadableExtensions,
@@ -39,12 +40,13 @@ import {
   type CompatAliasTarget,
   type ResolvedConfig,
 } from '../config'
-import { readText, toPosixPath } from '../utils/fs'
+import { readText, toPosixPath, writeText } from '../utils/fs'
 import {
   type ExternalLoadTarget,
   externalPackageImportTarget,
   getExternalPackagePolicy,
   isCommonJsModuleSource,
+  isEsmModuleFile,
   packageNameOfSpecifier,
   resolveImport,
   resolveExternalLoadTarget,
@@ -99,7 +101,7 @@ const buildQueue: (() => void)[] = []
 const moduleBuilds = new Map<string, Promise<string>>()
 const routeBundleBuilds = new Map<string, Promise<string>>()
 
-// PNEXT_DEV_MODULE_STATS=1: attribute every per-module compile to its profile,
+// PNEXT_TRACE=server: attribute every per-module compile to its profile,
 // so cross-profile duplicate work is countable rather than inferred. Counts are
 // load-insensitive, which is what makes them usable on a contended box.
 interface ModuleStat {
@@ -109,9 +111,9 @@ interface ModuleStat {
 }
 // `${profile}:${file}` of modules that fell off the oxc fast path onto esbuild.
 const esbuildFallbacks = new Set<string>()
-const moduleStats: Map<string, ModuleStat[]> | undefined =
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  process.env.PNEXT_DEV_MODULE_STATS === '1' ? new Map() : undefined
+const moduleStats: Map<string, ModuleStat[]> | undefined = traceEnabled('server')
+  ? new Map()
+  : undefined
 let moduleStatsFlush: Timer | undefined
 
 function noteModuleCompile(file: string, profile: string, ms: number, esbuild: boolean) {
@@ -163,10 +165,11 @@ function reportModuleStats() {
         `${duplicateCompiles} redundant compiles, ${duplicateMs.toFixed(0)} ms nested-wall`,
     ].join('\n'),
   )
-  // PNEXT_DEV_MODULE_STATS_OUT=<path>: also dump the per-file list, so a floor
-  // bench can replay the exact module set a route compiles in each profile.
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const out = process.env.PNEXT_DEV_MODULE_STATS_OUT
+  // PNEXT_TRACE=server=<path>: also dump the per-file list, so a floor bench can
+  // replay the exact module set a route compiles in each profile. A `.jsonl` path
+  // belongs to the heavy-package profile instead (see vendor.ts).
+  const out = traceValue('server')
+  if (out?.endsWith('.jsonl')) return
   if (!out) return
   const files = [...moduleStats.entries()].flatMap(([file, entries]) =>
     entries.map(entry => ({ file, profile: entry.profile, ms: entry.ms, esbuild: entry.esbuild })),
@@ -571,8 +574,7 @@ function startRouteVendorStage(config: ResolvedConfig, route: RouteManifestEntry
       }
     }
     for (const specifier of demand) dropped.delete(specifier)
-    // eslint-disable-next-line turbo/no-undeclared-env-vars
-    if (process.env.PNEXT_DEV_PROFILE) {
+    if (traceEnabled('server')) {
       console.log(
         `dev-import vendor seed walk ${route.route} in ${formatDuration(performance.now() - seedT0)} (kept ${demand.size}, dropped ${dropped.size})`,
       )
@@ -1873,26 +1875,21 @@ async function resolveDevModuleSpecifier(
     )
     return { path: `${pathToFileHref(stub)}${hash}`, external: true }
   }
-  // The compiled-path rewrite below is only safe for imports the WRITE pass walks:
-  // writeDevModuleUncached compiles the entry source's own local import targets, nothing deeper. A
-  // first-party compat runtime file pulled in by an alias that esbuild BUNDLES contributes its own
-  // relative imports through this hook, and nothing ever writes those into the profile cache - the
-  // import would resolve to a file that does not exist. Point such a transitive import at its own
-  // source instead; Bun compiles the `.ts` on import.
+  // A `require()` of an ES module cannot take the compiled-path rewrite: the artifact is ESM, and
+  // requiring one throws the moment it is not synchronously evaluable. Let esbuild bundle it and do
+  // the interop, exactly as the alias branch above already does for a require-call. Under an
+  // npm-layout install this is the common case - node_modules is INSIDE workspaceRoot, so a
+  // package's own ESM file counts as first-party source here.
+  if (kind === 'require-call' && isEsmModuleFile(resolved)) return { path: resolved }
   const importerFile = importer && !importer.startsWith('<') ? path.resolve(importer) : ''
+  // `importerFile !== file` keeps this to imports the write pass misses: the entry's OWN local
+  // imports are already walked by writeDevModuleUncached, so another importer means esbuild INLINED
+  // that module here and nobody compiles its relative siblings. It can never also key on the importer
+  // being out-of-workspace - under an npm-layout install pnext's runtime files live in the app's
+  // node_modules, and the sibling was then silently never written. Recompiling is not a risk:
+  // writeDevModule returns an already-written output as-is, so island identity survives navigation.
   const bundledCompatImporter =
-    isLocalSourceSpecifier &&
-    importerFile !== '' &&
-    importerFile !== path.resolve(file) &&
-    !isInside(config.workspaceRoot, importerFile) &&
-    !isInside(config.workspaceRoot, resolved)
-  // The `importerFile !== file` term above keeps this to imports the write pass misses: the entry's
-  // OWN local imports are already walked by writeDevModuleUncached. Everything deeper - a relative
-  // sibling of a compat file esbuild inlined into the entry - is nobody's job but this one, whether
-  // the entry is a workspace module or a node_modules-nested 'use client' component. Gating on an
-  // in-workspace entry left those nested client references importing a file that was never written.
-  // Recompiling is not a risk: writeDevModule returns an already-written output as-is, so island
-  // identity across a soft navigation is preserved.
+    isLocalSourceSpecifier && importerFile !== '' && importerFile !== path.resolve(file)
   if (bundledCompatImporter) {
     // Compile it here, keeping the same compiled-path rewrite so the module stays a single instance -
     // pointing at the raw source instead would load a SECOND copy of the compat runtime graph and split its
@@ -2422,6 +2419,14 @@ async function linkDirectoryAssetContext(
       }
       if (existsSync(target)) return
       await mkdir(path.dirname(target), { recursive: true })
+      // A package manifest linked whole makes the staged mirror a RESOLVABLE package: a bare
+      // `pkg/sub` import from a compiled artifact finds this copy first and fails on an `exports`
+      // subpath that only exists in the real tree. Stage the one field the mirror needs (`type`,
+      // which decides how a compiled `.js` sibling parses) and none of the resolution map.
+      if (entry.name === 'package.json') {
+        await writeText(target, await stagedManifestSource(source))
+        return
+      }
       try {
         await symlink(source, target, 'file')
       } catch {
@@ -2431,6 +2436,15 @@ async function linkDirectoryAssetContext(
   )
 }
 
+async function stagedManifestSource(file: string) {
+  try {
+    const manifest = JSON.parse(await readText(file)) as { type?: unknown }
+    return JSON.stringify(typeof manifest.type === 'string' ? { type: manifest.type } : {})
+  } catch {
+    return '{}'
+  }
+}
+
 // Recursively stage an asset directory: link non-code leaf files and recurse
 // into subdirectories, but never link code files — those compile through the
 // module graph into their own staged output and must not be shadowed by a raw
@@ -2535,8 +2549,7 @@ function uniqueFiles(files: string[]) {
 }
 
 async function profileDevImport<T>(label: string, task: () => Promise<T>) {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (!process.env.PNEXT_DEV_PROFILE) return task()
+  if (!traceEnabled('server')) return task()
   const start = performance.now()
   try {
     return await task()

package/src/runtime/vendor-build.ts

@@ -41,6 +41,7 @@ import {
 } from '../resolve/imports'
 import { clearNodeModulesResolutionCache } from '../resolve/engine'
 import { cachedExistsSync, clearNodeModulesFsCache } from '../utils/fs-cache'
+import { traceEnabled } from '../utils/trace-flags'
 import {
   clientReferenceExportNames,
   clientReferenceModuleSource,
@@ -729,8 +730,7 @@ export function vendorPreplanReport() {
   return { ...vendorPreplanStats, reasons: vendorPreplanStats.reasons.slice(0, 60) }
 }
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const vendorPreplanDebug = () => process.env.PNEXT_VENDOR_PREPLAN_DEBUG === '1'
+const vendorPreplanDebug = () => traceEnabled('vendor')
 let preplanReportFlush: ReturnType<typeof setTimeout> | undefined
 function schedulePreplanReport() {
   if (!vendorPreplanDebug()) return
@@ -1130,12 +1130,11 @@ async function buildVendorGroup(
   await emitNestedExternalTraceCopies(built[0]!.file, context.nestedExternalFiles)
 }
 
-// vendor plugin-callback attribution (PNEXT_VENDOR_PROFILE=1, dormant otherwise). Every
+// vendor plugin-callback attribution (PNEXT_TRACE=vendor, dormant otherwise). Every
 // onResolve/onLoad is an IPC round trip esbuild's bundler blocks on, against the one JS thread that
 // answers them; counts separate "our callbacks are slow" from "we answer many questions".
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const vendorProfileEnabled = process.env.PNEXT_VENDOR_PROFILE === '1'
+const vendorProfileEnabled = traceEnabled('vendor')
 const vendorProfileTotals = new Map<string, number>()
 
 function vendorProfileCount(key: string, by = 1) {
@@ -2532,8 +2531,7 @@ function isResolveFailure(error: unknown) {
 }
 
 async function profileRuntimeStep<T>(label: string, task: () => Promise<T>) {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (!process.env.PNEXT_DEV_PROFILE) return task()
+  if (!traceEnabled('server')) return task()
   const start = performance.now()
   try {
     return await task()

package/src/runtime/vendor.ts

@@ -42,6 +42,7 @@ import { isCommonJsModuleSource } from '../resolve/imports'
 import { outputSpecifiers } from './module-transform'
 import { escapeRegex, isIdentifier, uniqueIdentifier } from '../utils/code'
 import { cachedExistsSync } from '../utils/fs-cache'
+import { traceEnabled, traceValue } from '../utils/trace-flags'
 import { writeFileAtomic } from '../utils/fs'
 
 // --------------------------------------------------------------------------
@@ -217,7 +218,7 @@ function promoteVendorWork(work: VendorPromotable | undefined) {
 }
 
 // --------------------------------------------------------------------------
-// saturation trace (PNEXT_VENDOR_TRACE=1)
+// saturation trace (PNEXT_TRACE=vendor)
 // --------------------------------------------------------------------------
 
 /** One build's occupancy of a worker slot — the active-builds-over-time input. */
@@ -230,8 +231,7 @@ export interface VendorBuildSpan {
 
 const vendorSpans: VendorBuildSpan[] = []
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const vendorTracing = () => process.env.PNEXT_VENDOR_TRACE === '1'
+const vendorTracing = () => traceEnabled('vendor')
 
 function openVendorSpan(label: string, nested: boolean) {
   if (!vendorTracing()) return undefined
@@ -245,14 +245,13 @@ function closeVendorSpan(span: VendorBuildSpan | undefined) {
 }
 
 // --------------------------------------------------------------------------
-// TEMPORARY JSONL workload trace (PNEXT_VENDOR_TRACE=<path>)
+// TEMPORARY JSONL workload trace (PNEXT_TRACE=vendor=<path>)
 // --------------------------------------------------------------------------
 
-// A PATH-valued PNEXT_VENDOR_TRACE appends build/request/edge rows for
-// bench/tools/vendor-analyze.ts; `=1` still means the in-memory spans only.
+// A path-valued `vendor` scope appends build/request/edge rows for
+// bench/tools/vendor-analyze.ts; a bare `vendor` means the in-memory spans only.
 const vendorTraceFile = (() => {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const value = process.env.PNEXT_VENDOR_TRACE
+  const value = traceValue('vendor')
   if (!value || !(value.includes('/') || value.endsWith('.jsonl'))) return undefined
   return path.resolve(value)
 })()
@@ -881,7 +880,10 @@ const ESM_DIST_ENTRY_MARKER = 'entry'
 
 const esmDists = new Map<string, Promise<string | undefined>>()
 
-export function copyBrowserReadyEsmDist(entry: string, distDir: string) {
+export function copyBrowserReadyEsmDist(
+  entry: string,
+  distDir: string,
+): Promise<string | undefined> {
   // One copy per destination: a second copier would rewrite files the first has
   // already published, and copyFile is not atomic against a concurrent import.
   let dist = esmDists.get(distDir)
@@ -889,14 +891,24 @@ export function copyBrowserReadyEsmDist(entry: string, distDir: string) {
     dist = copyBrowserReadyEsmDistUncached(entry, distDir)
     esmDists.set(distDir, dist)
   }
-  return dist
+  // A `pnext build` wiping `.pnext` under this server deletes published copies out from under the
+  // memo; a bundle repointed at a vanished dist 500s on every import. Re-verify against disk and
+  // re-copy - the same only-the-stale-holder-evicts rule dropVendorBundle applies to bundles.
+  return dist.then(published => {
+    if (published === undefined || existsSync(published)) return published
+    if (esmDists.get(distDir) === dist) esmDists.delete(distDir)
+    return copyBrowserReadyEsmDist(entry, distDir)
+  })
 }
 
 async function copyBrowserReadyEsmDistUncached(entry: string, distDir: string) {
   const existing = await readFile(path.join(distDir, ESM_DIST_ENTRY_MARKER), 'utf8').catch(
     () => undefined,
   )
-  if (existing !== undefined) return path.join(distDir, existing)
+  // The marker without its entry is a half-deleted copy: fall through and rewrite it.
+  if (existing !== undefined && existsSync(path.join(distDir, existing))) {
+    return path.join(distDir, existing)
+  }
 
   const closure = await collectBrowserReadyEsmClosure(entry)
   if (!closure) return undefined
@@ -1050,8 +1062,12 @@ export function cjsNoFacadeMarker(bundleFile: string) {
 
 const facades = new Map<string, Promise<string | undefined>>()
 
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const heavyProfFile = process.env.PNEXT_HEAVY_PROF
+// A `.jsonl` value on the server scope selects this profile; any other path is the
+// per-module stats dump (runtime/modules.ts).
+const heavyProfFile = (() => {
+  const value = traceValue('server')
+  return value?.endsWith('.jsonl') ? value : undefined
+})()
 export function heavyProfRow(row: Record<string, unknown>) {
   if (!heavyProfFile) return
   try {

package/src/types.ts

@@ -56,11 +56,20 @@ export interface PNextAdapterConfig {
 }
 
 export interface PNextCompatConfig {
-  next?: boolean
+  next?: boolean | PNextNextCompatConfig
   react?: boolean
   reactCompiler?: boolean
 }
 
+/** Opt-in Next-compat behaviours. Everything here defaults off. */
+export interface PNextNextCompatConfig {
+  /**
+   * Next 15's transitional sync request APIs: cookies()/headers()/draftMode() return a Promise that
+   * also carries the sync surface, warning once per callsite. Off by default (Next 16 semantics).
+   */
+  legacyRequestAPIs?: boolean
+}
+
 export interface MetadataLink {
   rel: string
   url: string

package/src/utils/code.ts

@@ -36,3 +36,8 @@ export function uniqueIdentifier(source: string, base: string, ...used: string[]
 export function isIdentifier(value: string) {
   return /^[A-Za-z_$][\w$]*$/.test(value)
 }
+
+/** Source with comments removed; the `[^:]` guard keeps `://` inside string URLs intact. */
+export function stripComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
+}

package/src/utils/dev-profile.ts

@@ -1,5 +1,5 @@
 /**
- * Buffered sink for PNEXT_DEV_PROFILE lines. A warm request emits many phase lines, and writing each
+ * Buffered sink for PNEXT_TRACE=server lines. A warm request emits many phase lines, and writing each
  * straight to stdout inflated every enclosing span it sat inside - the measurement changed what it
  * measured. Lines accumulate here and the request handler flushes them in one write.
  */

package/src/utils/esbuild.ts

@@ -27,10 +27,45 @@ function track<T>(promise: Promise<T>): Promise<T> {
   })
 }
 
-export const build: typeof Esbuild.build = options => track(load().build(options))
+// A service killed out from under an in-flight call (memory watchdog, crash) fails it with this
+// exact message; the next call respawns the service, so one retry turns a user-visible 500 into
+// a slightly slower response.
+// "no longer running": issued against a dead cached service. "was stopped": in flight when a
+// stop() (watchdog or the reset below) tore the service down.
+const serviceDied = (error: unknown) =>
+  error instanceof Error &&
+  (error.message.includes('The service is no longer running') ||
+    error.message.includes('The service was stopped'))
+
+// esbuild caches the dead service until stop() resets it. The reset is epoch-guarded: every call
+// that raced the same dead service shares one stop(), because a second stop() would kill the fresh
+// child under the retries already running against it.
+let resetEpoch = 0
+let serviceReset: Promise<void> | undefined
+
+async function withServiceRetry<T>(run: () => Promise<T>): Promise<T> {
+  const epoch = resetEpoch
+  try {
+    return await track(run())
+  } catch (error) {
+    if (!serviceDied(error)) throw error
+    if (epoch === resetEpoch) {
+      serviceReset ??= Promise.resolve(esbuild?.stop())
+        .catch(() => undefined)
+        .then(() => {
+          resetEpoch += 1
+          serviceReset = undefined
+        })
+      await serviceReset
+    }
+    return track(run())
+  }
+}
+
+export const build: typeof Esbuild.build = options => withServiceRetry(() => load().build(options))
 
 export const transform: typeof Esbuild.transform = (input, options) =>
-  track(load().transform(input, options))
+  withServiceRetry(() => load().transform(input, options))
 
 /**
  * Spawn the resident service child ahead of the first real compile. Fire-and-forget: the spawn and

package/src/utils/trace-flags.ts

@@ -0,0 +1,66 @@
+/**
+ * `PNEXT_TRACE=<comma-separated scopes>` - the single umbrella for pnext's diagnostic output.
+ * The variable is parsed once, on first use; every later check is a map lookup on a boolean test,
+ * so a build with tracing off pays nothing.
+ *
+ * Grammar: entries are `scope` or `scope=value`, comma separated. `1` is an alias for `boot`
+ * (`PNEXT_TRACE=1` keeps its old meaning) and `all` turns on every scope.
+ * Example: `PNEXT_TRACE=boot,server=/tmp/modules.json`.
+ *
+ * A scope is all-or-nothing: turning one on turns on everything it covers.
+ *
+ * | scope    | prints / does                                                                     |
+ * | -------- | --------------------------------------------------------------------------------- |
+ * | `boot`   | boot-phase timings and memory readings                                            |
+ * | `server` | dev request / render / build timings, per-module compile attribution, route-facts and global-css hit/miss, cache-invalidation reasons, load-plugin registrations |
+ * | `vendor` | vendor saturation spans, esbuild plugin-callback attribution, preplan/native report |
+ * | `client` | client-build phase timings, and the esbuild metafile written to the output dir     |
+ * | `all`    | the four above                                                                    |
+ *
+ * Two scopes take a `=<path>` value:
+ * - `server=<path>` dumps the per-module compile list as JSON; a `.jsonl` path instead collects the
+ *   heavy-package facade profile (they are never wanted at once, and the suffix picks between them).
+ * - `vendor=<path>` appends the JSONL workload trace bench/tools/vendor-analyze.ts reads.
+ */
+
+/** Parse one raw `PNEXT_TRACE` value into scope -> value (`''` when the entry carried none). */
+export function parseTraceFlags(raw: string | undefined): Map<string, string> {
+  const scopes = new Map<string, string>()
+  for (const entry of raw?.split(',') ?? []) {
+    const trimmed = entry.trim()
+    if (!trimmed) continue
+    const eq = trimmed.indexOf('=')
+    const name = eq === -1 ? trimmed : trimmed.slice(0, eq).trim()
+    if (!name) continue
+    scopes.set(name === '1' ? 'boot' : name, eq === -1 ? '' : trimmed.slice(eq + 1).trim())
+  }
+  return scopes
+}
+
+let scopes: Map<string, string> | undefined
+let all = false
+
+function flags() {
+  if (!scopes) {
+    // eslint-disable-next-line turbo/no-undeclared-env-vars
+    scopes = parseTraceFlags(process.env.PNEXT_TRACE)
+    all = scopes.has('all')
+  }
+  return scopes
+}
+
+/** Drop the memoized parse - for tests and benches that flip PNEXT_TRACE in-process. */
+export function resetTraceFlags() {
+  scopes = undefined
+  all = false
+}
+
+/** True when `scope` (or `all`) is listed in PNEXT_TRACE, with or without a value. */
+export function traceEnabled(scope: string): boolean {
+  return flags().has(scope) || all
+}
+
+/** The `scope=<value>` payload, or undefined when the scope is absent or valueless. */
+export function traceValue(scope: string): string | undefined {
+  return flags().get(scope) || undefined
+}