@wular/pnext 0.0.9 → 0.0.11

package/src/compat/next/headers.ts

@@ -2,9 +2,11 @@ import {
   currentRequest,
   currentResponseHeaders,
   getWorkUnit,
+  legacyRequestAPIs,
   requireRequest,
   requestApiPromise,
 } from '../../request/context'
+import { withSyncAccess } from './legacy-request-apis'
 import type { NextRequestCookies } from '../../types'
 import {
   assertDraftModeToggleAllowedInAfter,
@@ -63,9 +65,9 @@ export function headers() {
   assertRequestApiAllowedInAfter('headers()')
   assertDynamicErrorRequestApi('headers()')
   assertNoDynamicApiInsideCache('headers()')
-  return requestApiPromise('headers()', () =>
-    readonlyHeaders(new Headers(requireRequest('headers()').headers)),
-  )
+  const produce = () => readonlyHeaders(new Headers(requireRequest('headers()').headers))
+  const promise = requestApiPromise('headers()', produce)
+  return legacyRequestAPIs() ? withSyncAccess(promise, 'headers', produce) : promise
 }
 
 export interface CookieSetOptions {
@@ -91,7 +93,9 @@ export function cookies() {
   assertRequestApiAllowedInAfter('cookies()')
   assertDynamicErrorRequestApi('cookies()')
   assertNoDynamicApiInsideCache('cookies()')
-  return requestApiPromise('cookies()', () => wrapCookieJar(requireRequest('cookies()').cookies))
+  const produce = () => wrapCookieJar(requireRequest('cookies()').cookies)
+  const promise = requestApiPromise('cookies()', produce)
+  return legacyRequestAPIs() ? withSyncAccess(promise, 'cookies', produce) : promise
 }
 
 export function assertDynamicErrorRequestApi(
@@ -225,7 +229,7 @@ export function draftMode(): Promise<DraftMode> {
   // draft is simply off, so reading isEnabled must not postpone or throw.
   const request = currentRequest()
   const requestCookies = request?.cookies
-  return Promise.resolve({
+  const draft: DraftMode = {
     get isEnabled() {
       return requestCookies?.has(draftCookieName) ?? false
     },
@@ -247,7 +251,9 @@ export function draftMode(): Promise<DraftMode> {
         `${draftCookieName}=; Path=/; Max-Age=0; HttpOnly; SameSite=None; Secure`,
       )
     },
-  })
+  }
+  const promise = Promise.resolve(draft)
+  return legacyRequestAPIs() ? withSyncAccess(promise, 'draftMode', () => draft) : promise
 }
 
 function bypassToken() {

package/src/compat/next/image/client.tsx

@@ -1,4 +1,5 @@
 'use client'
+/** @jsxImportSource preact */
 
 import {
   forwardRef,

package/src/compat/next/image.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import { registerResourceHint } from '../../render/resource-hints'
 import { forwardRef } from 'preact/compat'
 import ClientImage from './image/client'

package/src/compat/next/legacy-image.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import { forwardRef } from 'preact/compat'
 import { registerResourceHint } from '../../render/resource-hints'
 import { getImagesConfig, resolveImageProps } from './image/props'

package/src/compat/next/legacy-request-apis.ts

@@ -0,0 +1,62 @@
+// Next 15's transitional sync request APIs, behind compat.next.legacyRequestAPIs. cookies()/headers()/
+// draftMode() still return a Promise, but that promise also carries the resolved value's surface, so
+// Next-14-era code (`cookies().get('x')`) keeps working while it migrates to `await`. Each sync access
+// logs Next's sync-dynamic-apis deprecation warning, deduped by userland callsite.
+//
+// Nothing here is reachable — or even allocated — when the option is off.
+
+import { currentRenderCacheMeta } from '../cache/revalidate'
+
+const PROMISE_PROPS = new Set<PropertyKey>(['then', 'catch', 'finally', 'constructor'])
+const warned = new Set<string>()
+
+/**
+ * Wrap a request-API promise so unawaited property reads hit the produced value. The value is produced
+ * lazily (and once), so a promise nobody touches synchronously costs a single Proxy.
+ */
+export function withSyncAccess<T extends object>(
+  promise: Promise<T>,
+  api: 'cookies' | 'headers' | 'draftMode',
+  produce: () => T,
+): Promise<T> {
+  let value: T | undefined
+  const resolve = () => (value ??= produce())
+  return new Proxy(promise, {
+    get(target, prop) {
+      if (PROMISE_PROPS.has(prop) || prop === Symbol.toStringTag) {
+        const own: unknown = Reflect.get(target, prop, target)
+        return typeof own === 'function'
+          ? (own as (...args: unknown[]) => unknown).bind(target)
+          : own
+      }
+      warnSyncAccess(api, prop)
+      const source = resolve() as object
+      const read: unknown = Reflect.get(source, prop, source)
+      return typeof read === 'function'
+        ? (read as (...args: unknown[]) => unknown).bind(source)
+        : read
+    },
+  })
+}
+
+function warnSyncAccess(api: string, prop: PropertyKey): void {
+  const expression =
+    prop === Symbol.iterator
+      ? `\`...${api}()\` or similar iteration`
+      : `\`${api}().${String(prop)}\``
+  const route = currentRenderCacheMeta()?.route
+  const key = `${route ?? ''}|${expression}|${callsite()}`
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(
+    `${route ? `Route "${route}" ` : 'This route '}used ${expression}. ` +
+      `\`${api}()\` should be awaited before using its value. ` +
+      'Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis',
+  )
+}
+
+/** First stack frame outside this module — the userland call site Next dedupes on. */
+function callsite(): string {
+  const frames = new Error().stack?.split('\n').slice(1) ?? []
+  return frames.find(frame => !frame.includes('legacy-request-apis')) ?? ''
+}

package/src/compat/next/link.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 // preact core + hooks only (no preact/compat): this module rides in every compat app's first-page
 // bundle, and the lite client tier must not pull compat through it. Children.only/count are replaced
 // with toChildArray below; the ref arrives React-19-style as a prop (the parity vnode pass moves

package/src/compat/next/rewrites.ts

@@ -163,6 +163,13 @@ export function compileSource(source: string): { regex: RegExp; paramNames: stri
       parts.push('([^/]+)')
       continue
     }
+    // A bare regex group segment — `/(.*)` is Next's documented way to match
+    // every path in a headers rule. Non-capturing so it never shifts the
+    // capture indexes the named params above are read from.
+    if (segment.startsWith('(') && segment.endsWith(')')) {
+      parts.push(`(?:${segment.slice(1, -1)})`)
+      continue
+    }
     // Plain literal segments may carry regex-significant filename characters
     // (`favicon.ico`, `sitemap.xml`) — escape them. Anything with actual
     // pattern syntax beyond that is unsupported.

package/src/compat/next/script.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import type { JSX } from 'preact'
 import { escapeHtml } from '../../utils/html'
 import { getNextConfig } from './config-loader'

package/src/compat/register/bundler.ts

@@ -514,7 +514,12 @@ function serverSourceLoadPlugin(
         // `use client` in a CommonJS file -> tag its exports as references.
         if (/\.c?js$/.test(args.path)) {
           const references = await clientReferenceLoad(args.path)
-          if (references) return references
+          if (references) {
+            // On the react-server layer the boundary stub wins over the in-place tag: a CommonJS
+            // `'use client'` leaf (a package's own `require()`d client half) must never EVALUATE
+            // server-side, exactly like the ESM ones this same scan already replaces.
+            return (await vendorClientBoundary?.(args.path)) ?? references
+          }
         }
         // First-party (or transpilePackages-opted) source: font/OPI rewrites.
         // Everything else under node_modules keeps esbuild's native load path.

package/src/compat/segment/loading-boundary.ts

@@ -11,7 +11,7 @@
 
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
-import { escapeRegex as escapeRegExp } from '../../utils/code'
+import { escapeRegex as escapeRegExp, stripComments } from '../../utils/code'
 
 /**
  * True when the route's PAGE file wraps content in a React `<Suspense>`.
@@ -105,7 +105,3 @@ function namespaceBindings(clauses: readonly string[]): string[] {
   }
   return names
 }
-
-function stripComments(source: string): string {
-  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
-}

package/src/compat/validation/validate.ts

@@ -16,6 +16,7 @@ import type { ResolvedConfig } from '../../config'
 import { extraPageExtensions } from '../../extensions'
 import type { RouteManifestEntry } from '../../types'
 import { getNextConfig } from '../next/config-loader'
+import { stripComments } from '../../utils/code'
 import {
   conflictingAppAndPageMessage,
   conflictingParallelPagesMessage,
@@ -246,7 +247,9 @@ function validateStaticImageImports(config: ResolvedConfig, routes: RouteManifes
       if (!isAppSourceFile(config, file)) continue
       const source = readSource(file)
       if (!source) continue
-      const imports = source.matchAll(
+      // Comment-stripped: a commented-out image import (or a doc-comment example) is not an
+      // import, and webpack under Next would never error on one.
+      const imports = stripComments(source).matchAll(
         /\bimport\s+(?:[^'";]+?\s+from\s+)?['"]([^'"]+\.(?:png|jpe?g|gif|webp|avif|ico|bmp|svg))['"]/gi,
       )
       for (const match of imports) {
@@ -376,7 +379,12 @@ function routeFiles(route: RouteManifestEntry): string[] {
 function isAppSourceFile(config: ResolvedConfig, file: string): boolean {
   if (isInside(config.outPath, file)) return false
   const relative = path.relative(config.root, file)
-  if (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)) return true
+  if (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+    // A standalone npm layout keeps node_modules INSIDE the root; framework-supplied route
+    // files (pnext's own defaults) are not app sources and must never be validated as such
+    // (a JSDoc example in pnext's extensions.ts failed a real app's build as './pic.png').
+    return !relative.split(path.sep).includes('node_modules')
+  }
   return (
     file.includes(`${path.sep}source-app${path.sep}`) ||
     file.includes(`${path.sep}source-pages${path.sep}`)

package/src/config.ts

@@ -5,6 +5,7 @@ import { loadEnv } from './env'
 import { findWorkspaceRoot } from './resolve/imports'
 import { PREFETCH_MODES, type PNextConfig } from './types'
 import { setCacheComponents } from './render/ppr'
+import { setLegacyRequestAPIs } from './request/context'
 
 export type ResolvedConfig = Required<Pick<PNextConfig, 'outDir' | 'basePath'>> &
   Omit<PNextConfig, 'outDir' | 'basePath'> & {
@@ -83,10 +84,20 @@ export async function loadConfig(
     ...(loadedConfig.default ?? {}),
     // eslint-disable-next-line turbo/no-undeclared-env-vars
     ...(process.env.PNEXT_COMPAT === 'next'
-      ? { compat: { ...(loadedConfig.default?.compat ?? {}), next: true } }
+      ? {
+          compat: {
+            ...(loadedConfig.default?.compat ?? {}),
+            // An object `next` already enables compat — keep its options rather than flattening to true.
+            next: loadedConfig.default?.compat?.next || true,
+          },
+        }
       : {}),
   }
   validateConfig(config)
+  // Per-app flag on a process-global cell (like cacheComponents): always written, never inherited.
+  setLegacyRequestAPIs(
+    typeof config.compat?.next === 'object' && config.compat.next.legacyRequestAPIs === true,
+  )
   // cacheComponents is a per-app flag on a process-global cell: clear it before
   // the next.config source re-derives it, so a pure-core (or flag-off) app
   // loaded after a cacheComponents app never inherits the previous build's flag.

package/src/css/build.ts

@@ -282,6 +282,7 @@ export async function buildGlobalCss(config: ResolvedConfig, options: CssBuildOp
       .join(', ')}`,
   )
 
+  const postcss = hasPostcssConfig(config.root)
   await log.step('global css: esbuild bundle', () =>
     build({
       stdin: {
@@ -295,7 +296,7 @@ export async function buildGlobalCss(config: ResolvedConfig, options: CssBuildOp
       minify: !options.dev,
       conditions: ['style', 'browser'],
       assetNames: 'files/[name]-[hash]',
-      plugins: getCssExtensions().cssChunkPlugins(),
+      plugins: [...getCssExtensions().cssChunkPlugins(), ...cssDirectiveOrderPlugins(postcss)],
       loader: {
         '.css': 'css',
         '.module.css': 'css',
@@ -311,7 +312,7 @@ export async function buildGlobalCss(config: ResolvedConfig, options: CssBuildOp
       },
     }),
   )
-  if (hasPostcssConfig(config.root)) {
+  if (postcss) {
     await rewriteTailwindConfigDirectives(outfile, sources)
     await log.step('global css: postcss', () =>
       runPostcssOffThread(config, outfile, options, sources[0]),
@@ -473,6 +474,7 @@ async function bundleCssChunk(
 
   log.log(`${label}: ${cssImports.length} import${cssImports.length === 1 ? '' : 's'}`)
 
+  const postcss = hasPostcssConfig(config.root)
   await build({
     stdin: {
       contents: cssImports.map(file => `@import ${JSON.stringify(file)};`).join('\n'),
@@ -488,7 +490,11 @@ async function bundleCssChunk(
     conditions: ['style', 'browser'],
     assetNames: 'files/[name]-[hash]',
     // Lazy registry read: compat (sass) plugins register at bootstrap.
-    plugins: [...getCssExtensions().cssChunkPlugins(), cssModuleBuildPlugin()],
+    plugins: [
+      ...getCssExtensions().cssChunkPlugins(),
+      cssModuleBuildPlugin(),
+      ...cssDirectiveOrderPlugins(postcss),
+    ],
     loader: {
       '.css': 'css',
       '.module.css': 'css',
@@ -504,7 +510,7 @@ async function bundleCssChunk(
     },
   })
 
-  if (hasPostcssConfig(config.root)) {
+  if (postcss) {
     await rewriteTailwindConfigDirectives(outfile, cssImports)
     await log.step(`${label}: postcss`, () => runPostcssOffThread(config, outfile, options))
   }
@@ -554,6 +560,107 @@ export function cssModuleClientPlugin(): Plugin {
   }
 }
 
+// Tailwind's own pipeline consumes @source/@plugin/@config wherever they sit, so apps write them
+// above their @import lines. esbuild bundles first and rejects any @import that follows another
+// rule ("invalid-@import"), leaving that sheet unbundled — a broken stylesheet. Only postcss apps
+// can have these directives, so plain-CSS apps keep esbuild's native (plugin-free) load path.
+function cssDirectiveOrderPlugins(postcss: boolean): Plugin[] {
+  return postcss ? [cssDirectiveOrderPlugin()] : []
+}
+
+function cssDirectiveOrderPlugin(): Plugin {
+  return {
+    name: 'pnext-css-directive-order',
+    setup(plugin) {
+      plugin.onLoad({ filter: /\.css$/ }, async ({ path: file }) => ({
+        contents: hoistCssImports(await readText(file)),
+        loader: 'css',
+        resolveDir: path.dirname(file),
+      }))
+    },
+  }
+}
+
+/** At-rules that configure Tailwind and emit no CSS, so their position is free. */
+const CSS_CONFIG_AT_RULES = new Set(['source', 'plugin', 'config'])
+
+/**
+ * Move leading @import statements above the Tailwind config directives they follow. Only the
+ * statement prefix of the file is considered: the first rule that is neither an @import, a
+ * config directive, a comment nor @charset stops the scan, so real CSS never moves.
+ */
+export function hoistCssImports(source: string) {
+  if (!/@(?:source|plugin|config)\b/.test(source)) return source
+
+  const imports: string[] = []
+  const others: string[] = []
+  let charset = ''
+  let sawDirective = false
+  let hoist = false
+  let index = 0
+
+  while (index < source.length) {
+    const code = source.charCodeAt(index)
+    // space, tab, LF, CR, FF — CSS whitespace, without a regex call per character.
+    if (code === 32 || code === 9 || code === 10 || code === 13 || code === 12) {
+      index += 1
+      continue
+    }
+    const char = source[index]!
+    if (char === '/' && source[index + 1] === '*') {
+      const end = source.indexOf('*/', index + 2)
+      if (end === -1) break
+      others.push(source.slice(index, end + 2))
+      index = end + 2
+      continue
+    }
+    const name = char === '@' ? /^@([\w-]+)/.exec(source.slice(index))?.[1] : undefined
+    if (!name) break
+    if (name !== 'import' && name !== 'charset' && !CSS_CONFIG_AT_RULES.has(name)) break
+    const end = statementEnd(source, index)
+    if (end === -1) break
+
+    const statement = source.slice(index, end)
+    if (name === 'charset') charset ||= statement
+    else if (name === 'import') {
+      imports.push(statement)
+      if (sawDirective) hoist = true
+    } else {
+      others.push(statement)
+      sawDirective = true
+    }
+    index = end
+  }
+
+  if (!hoist) return source
+  return `${[charset, ...imports, ...others].filter(Boolean).join('\n')}\n${source.slice(index)}`
+}
+
+/** End offset (past the `;`) of a block-less at-rule, or -1 if it isn't one. */
+function statementEnd(source: string, start: number) {
+  for (let index = start; index < source.length; index += 1) {
+    const char = source[index]!
+    if (char === ';') return index + 1
+    if (char === '{' || char === '}') return -1
+    if (char === '"' || char === "'") {
+      index = skipString(source, index)
+      if (index === -1) return -1
+    }
+  }
+  return -1
+}
+
+/** Index of the closing quote of the string starting at `start`, or -1. */
+function skipString(source: string, start: number) {
+  const quote = source[start]
+  for (let index = start + 1; index < source.length; index += 1) {
+    const char = source[index]
+    if (char === '\\') index += 1
+    else if (char === quote) return index
+  }
+  return -1
+}
+
 function cssModuleBuildPlugin(): Plugin {
   return {
     name: 'pnext-css-module-build',

package/src/dev/internal-error.ts

@@ -0,0 +1,128 @@
+// Dev-only loud page for errors that originate inside pnext itself. App errors keep the normal
+// error/global-error documents; a framework failure instead gets the full trace and a prefilled
+// GitHub issue, because "This page couldn't load" hides exactly the information a bug report needs.
+
+import { pnextVersionRange } from '../utils/fs'
+import { escapeHtml } from '../utils/html'
+
+const ISSUES_URL = 'https://github.com/muzam1l/pnext/issues/new'
+// Keep the prefilled issue URL well under browser/GitHub limits.
+const MAX_ISSUE_BODY = 5_000
+
+const FRAME_PATH = /\(?((?:file:\/\/)?\/[^\s):]+)(?::\d+){0,2}\)?/
+
+/**
+ * A located stack frame is "pnext" when it resolves inside pnext's own source (a workspace
+ * checkout's `pnext/src/` or an installed `@wular/pnext/`). The error classifies as internal when
+ * every located frame is pnext — one app or foreign-package frame means app code was on the throw
+ * path and the normal error documents apply.
+ */
+export function isPnextInternalError(error: unknown): boolean {
+  if (!(error instanceof Error) || !error.stack) return false
+  let located = 0
+  for (const line of error.stack.split('\n').slice(1)) {
+    const file = FRAME_PATH.exec(line)?.[1]
+    if (!file || file.includes('native')) continue
+    located += 1
+    const pnextOwn =
+      file.includes('/@wular/pnext/') || /\/pnext\/(src|dist)\//.test(file.replace(/\\/g, '/'))
+    if (!pnextOwn) return false
+  }
+  return located > 0
+}
+
+export interface InternalErrorContext {
+  error: Error
+  route: string
+  url: string
+  digest?: string
+}
+
+function reportUrl(context: InternalErrorContext, version: string): string {
+  const title = `[dev] ${context.error.message.split('\n')[0]!.slice(0, 90)}`
+  // Home-relative paths: less noise, and the reporter's username stays out of the issue.
+  const stack = (context.error.stack ?? context.error.message)
+    .split('\n')
+    .map(line => {
+      const file = FRAME_PATH.exec(line)?.[1]
+      return file ? line.replace(file, shortPath(file)) : line
+    })
+    .join('\n')
+  const runtime = `${typeof Bun !== 'undefined' ? `bun ${Bun.version}` : `node ${process.version}`} · ${process.platform} ${process.arch}`
+  const body = [
+    `**pnext:** ${version} (dev)`,
+    `**Runtime:** ${runtime}`,
+    `**Route:** \`${context.route}\``,
+    context.digest ? `**Digest:** \`${context.digest}\`` : '',
+    '',
+    '**Error:**',
+    '```',
+    stack.slice(0, MAX_ISSUE_BODY),
+    '```',
+    '',
+    '<!-- What were you doing when this happened? Does it reproduce after a reload? -->',
+  ]
+    .filter(Boolean)
+    .join('\n')
+  return `${ISSUES_URL}?title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`
+}
+
+const css = `:root{--bg:#fafafa;--fg:#1a1a1a;--muted:#767676;--faint:#ababab;--accent:#c43030;--card:#f1f1f1;--border:rgba(0,0,0,.09);--btn-bg:#1a1a1a;--btn-fg:#fafafa}
+@media (prefers-color-scheme:dark){:root{--bg:#111;--fg:#e6e6e6;--muted:#888;--faint:#5c5c5c;--accent:#f07878;--card:#1a1a1a;--border:rgba(255,255,255,.09);--btn-bg:#e6e6e6;--btn-fg:#111}}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);font-family:system-ui,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;-webkit-font-smoothing:antialiased;min-height:100vh;display:flex;align-items:center;justify-content:center}
+main{width:min(640px,calc(100vw - 32px));background:var(--card);border:1px solid var(--border);border-radius:8px;padding:24px 26px;box-shadow:0 8px 32px rgba(0,0,0,.12);margin:24px 0}
+.badge{display:inline-block;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11px;font-weight:500;letter-spacing:.08em;text-transform:uppercase;color:var(--accent);margin-bottom:14px}
+h1{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:14.5px;font-weight:600;margin:0 0 8px;line-height:1.55;overflow-wrap:anywhere}
+p.meta{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11px;color:var(--muted);margin:0 0 18px;overflow-wrap:anywhere}
+.trace{background:var(--bg);border:1px solid var(--border);border-radius:5px;padding:12px 14px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:11.5px;line-height:1.9;overflow:auto;max-height:280px}
+.frame{white-space:nowrap}
+.frame .fn{color:var(--fg)}
+.frame .loc{color:var(--muted);margin-left:12px}
+.frame.native{color:var(--faint)}
+.frame.native .loc{color:var(--faint)}
+.actions{display:flex;gap:8px;margin-top:18px;flex-wrap:wrap}
+.actions a,.actions button{display:inline-flex;align-items:center;height:30px;padding:0 12px;font-family:inherit;font-size:12.5px;font-weight:500;border-radius:5px;cursor:pointer;text-decoration:none;border:1px solid var(--border);background:transparent;color:var(--fg)}
+.actions .primary{background:var(--btn-bg);color:var(--btn-fg);border:1px solid transparent}
+p.note{font-size:12px;color:var(--muted);margin:16px 0 0;line-height:1.6}`
+
+// `at fn (path:line:col)` / `at path:line:col`; frames render as aligned fn + location rows.
+const FRAME = /^\s*at\s+(?:(.+?)\s+\()?(.+?)(?::(\d+):(\d+))?\)?\s*$/
+
+function shortPath(file: string): string {
+  const modules = file.lastIndexOf('node_modules/')
+  if (modules >= 0) return file.slice(modules + 'node_modules/'.length)
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const home = process.env.HOME
+  return home && file.startsWith(home) ? `~${file.slice(home.length)}` : file
+}
+
+function traceHtml(stack: string): string {
+  const rows = stack
+    .split('\n')
+    .slice(1)
+    .map(line => {
+      const match = FRAME.exec(line)
+      if (!match) return `<div class="frame native">${escapeHtml(line.trim())}</div>`
+      const [, fn, file, lineNo, col] = match
+      const native = !file!.startsWith('/') && !file!.startsWith('file:')
+      const location = native ? file! : `${shortPath(file!)}${lineNo ? `:${lineNo}:${col}` : ''}`
+      return `<div class="frame${native ? ' native' : ''}"><span class="fn">${escapeHtml(fn ?? '<anonymous>')}</span><span class="loc">${escapeHtml(location)}</span></div>`
+    })
+  return rows.join('')
+}
+
+/** The full standalone document (own `<html>`), served like a global-error page. Dev only. */
+export function internalErrorHtml(context: InternalErrorContext): string {
+  const version = pnextVersionRange().slice(1)
+  const rawStack = context.error.stack ?? context.error.message
+  const details = [
+    `pnext ${version}`,
+    context.route,
+    context.digest ? `digest ${context.digest}` : '',
+    context.url,
+  ]
+    .filter(Boolean)
+    .join('  ·  ')
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>pnext internal error</title><style>${css}</style></head><body><main><span class="badge">pnext internal error</span><h1>${escapeHtml(context.error.message.split('\n')[0]!)}</h1><p class="meta">${escapeHtml(details)}</p><div class="trace" data-raw="${escapeHtml(rawStack)}">${traceHtml(rawStack)}</div><div class="actions"><a class="primary" href="${escapeHtml(reportUrl(context, version))}" target="_blank" rel="noreferrer">Report on GitHub</a><button onclick="navigator.clipboard.writeText(document.querySelector('.trace').dataset.raw).then(()=>{this.textContent='Copied'})">Copy trace</button><form style="margin:0"><button type="submit">Reload</button></form></div><p class="note">This error came from inside pnext, not your application code. Reload usually recovers in dev; if it repeats, the GitHub report above is prefilled with everything we know.</p></main></body></html>`
+}

package/src/dev/restart/global-css.ts

@@ -14,6 +14,7 @@ import { mkdirSync, existsSync, readFileSync, statSync, writeFileSync } from 'no
 import path from 'node:path'
 import type { ResolvedConfig } from '../../config'
 import { setGlobalCssSourceStore, type GlobalCssSourceStore } from '../../css/build'
+import { traceEnabled } from '../../utils/trace-flags'
 import { restartCacheEnabled } from './enabled'
 
 /** `[file, mtimeMs, size, contentHash]` — the shape the other restart caches use. */
@@ -212,9 +213,8 @@ function revalidate(files: SourceEntry[]): SourceEntry[] | undefined {
   return moved ? checked : files
 }
 
-/** Bisect seam: `PNEXT_DEV_GLOBAL_CSS_STATS=1` prints the hit/miss split at exit. */
+/** Bisect seam: `PNEXT_TRACE=server` prints the hit/miss split at exit. */
 const stats = { hits: 0, misses: 0 }
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-if (process.env.PNEXT_DEV_GLOBAL_CSS_STATS === '1') {
+if (traceEnabled('server')) {
   process.on('exit', () => console.log(`global-css hits=${stats.hits} misses=${stats.misses}`))
 }

package/src/dev/restart/route-facts.ts

@@ -17,6 +17,7 @@ import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import type { ResolvedConfig } from '../../config'
 import { setRouteFactsStore, type RouteFacts, type RouteFactsStore } from '../../routing/routes'
+import { traceEnabled } from '../../utils/trace-flags'
 import { restartCacheEnabled } from './enabled'
 
 /** `[file, mtimeMs, size, contentHash]` — the same record shape the key cache uses. */
@@ -215,9 +216,8 @@ function revalidate(files: SourceEntry[]): SourceEntry[] | undefined {
   return moved ? checked : files
 }
 
-/** Bisect seam: `PNEXT_DEV_FACTS_STATS=1` prints the hit/miss split at exit. */
+/** Bisect seam: `PNEXT_TRACE=server` prints the hit/miss split at exit. */
 const stats = { hits: 0, misses: 0 }
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-if (process.env.PNEXT_DEV_FACTS_STATS === '1') {
+if (traceEnabled('server')) {
   process.on('exit', () => console.log(`route-facts hits=${stats.hits} misses=${stats.misses}`))
 }

package/src/dev/server.ts

@@ -72,6 +72,7 @@ import {
 import { setRequestRuntime } from '../routing/request-environment'
 import { ensureDir, listFiles, writeText } from '../utils/fs'
 import { contentType } from '../utils/content-type'
+import { traceEnabled } from '../utils/trace-flags'
 import {
   flushDevProfileLines,
   formatProfileDuration,
@@ -888,8 +889,7 @@ interface DevRequestProfile {
 }
 
 function devRequestProfile(request: Request, url: URL): DevRequestProfile | undefined {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (!process.env.PNEXT_DEV_PROFILE) return undefined
+  if (!traceEnabled('server')) return undefined
   return {
     label: `${request.method} ${url.pathname}`,
     start: performance.now(),