@wular/pnext 0.0.9 → 0.0.11

package/package.json

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

package/reference/dev.md

@@ -56,7 +56,20 @@ Vercel has a dedicated adapter: `pnext build --adapter vercel` writes Build Outp
 
 - `PNEXT_COMPAT=next`: Next compatibility without a config file. See [Compatibility](./compat.md).
 - `PNEXT_TYPECHECK=classic`: in-process TypeScript checker instead of the native one.
-- `PNEXT_CLIENT_METAFILE=1`: write the client esbuild metafile to the output directory.
-- `PNEXT_CLIENT_PROFILE=1`: print client-build phase timings.
-- `PNEXT_DEV_PROFILE=1`: print dev request and build timings.
-- `PNEXT_BOOT_TRACE=1`: print boot-phase timings and memory readings.
+- `PNEXT_TRACE=<scopes>`: turn on diagnostic output. Comma-separated scopes, each `scope` or
+  `scope=value`; `1` means `boot`. A scope is all-or-nothing — it turns on everything it covers.
+  Example: `PNEXT_TRACE=boot,server=/tmp/modules.json`.
+
+| scope    | prints / does                                                                                                                                                           |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `boot`   | boot-phase timings and memory readings                                                                                                                                  |
+| `server` | dev request, render and build timings; per-module compile attribution; route-facts and global-css hit/miss; why each artifact was recompiled; load-plugin registrations |
+| `vendor` | vendor saturation spans, esbuild plugin-callback attribution, and the preplan / native decision report                                                                  |
+| `client` | client-build phase timings, plus the esbuild metafile written into the output directory                                                                                 |
+| `all`    | the four above                                                                                                                                                          |
+
+Two scopes take a `=<path>` value:
+
+- `server=<path>` dumps the per-module compile list as JSON. A `.jsonl` path collects the
+  heavy-package facade profile instead — the two are never wanted at once, so the suffix picks.
+- `vendor=<path>` appends the JSONL workload trace `bench/tools/vendor-analyze.ts` reads.

package/src/api/dynamic.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import { h, type ComponentType } from 'preact'
 import { useEffect, useRef, useState } from 'preact/hooks'
 

package/src/api/link.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import { h, type ComponentChildren, type JSX } from 'preact'
 import { useEffect, useRef } from 'preact/hooks'
 import type { AnchorHTMLAttributes, MouseEvent, ReactNode } from 'react'

package/src/cli/analyze.ts

@@ -474,7 +474,7 @@ function printAnalyzeFiles(result: AnalyzeResult, options: { details: boolean })
     console.log(
       `Other files: ${formatFileCount(sorted)}  ${formatTotalSize(sorted, result.compression)}`,
     )
-    console.log('Run pnext analyze --files to list them.')
+    console.log('List them: pnext analyze --files')
     return
   }
 

package/src/cli/boot/trace.ts

@@ -1,22 +1,54 @@
 /**
- * Boot phase timings for `pnext dev`, printed when `PNEXT_BOOT_TRACE=1`.
+ * Boot phase timings for `pnext dev`, printed only under `PNEXT_TRACE=boot` (or `=1`).
  *
  * Timestamps are `performance.now()`, whose origin is process start, so the
  * first mark's absolute value is everything before it: the bun runtime coming
- * up plus this module graph evaluating. Off, a mark costs one already-resolved
- * boolean test.
+ * up plus this module graph evaluating. Off, a mark costs one clock read and
+ * one rss read; nothing is ever printed.
  */
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const enabled = process.env.PNEXT_BOOT_TRACE === '1'
+import { loadavg, cpus, arch, platform } from 'node:os'
+import { existsSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+import { traceEnabled } from '../../utils/trace-flags'
+
+const enabled = traceEnabled('boot')
 const marks: [string, number, number][] = []
 
+// Bun (<=1.3.x) lacks the memoryUsage.rss fast path Node has.
+const rss = () =>
+  typeof process.memoryUsage.rss === 'function'
+    ? process.memoryUsage.rss()
+    : process.memoryUsage().rss
+
 export function markBoot(name: string) {
-  if (enabled) marks.push([name, performance.now(), process.memoryUsage.rss()])
+  if (enabled) marks.push([name, performance.now(), rss()])
+}
+
+// Environment facts a slow-boot report needs alongside the stage timings: the same trace on a
+// loaded box, a cold cache, or a huge node_modules reads completely differently.
+function traceHeader(): string[] {
+  const load = loadavg()
+    .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}`,
+  ]
+}
+
+function countTopLevel(dir: string): number {
+  try {
+    return readdirSync(path.resolve(dir)).length
+  } catch {
+    return 0
+  }
 }
 
 export function printBootTrace() {
   if (!enabled || marks.length === 0) return
-  const lines = ['boot trace (ms since process start):']
+  const lines = ['boot trace (ms since process start):', ...traceHeader()]
   let previous = 0
   for (const [name, at, rss] of marks) {
     const mb = (rss / 1048576).toFixed(0).padStart(5)
@@ -25,5 +57,6 @@ export function printBootTrace() {
     )
     previous = at
   }
+  lines.push(`  total            @${performance.now().toFixed(1)}`)
   console.log(lines.join('\n'))
 }

package/src/cli/build.ts

@@ -1086,8 +1086,8 @@ function printBuildSummary(
   }
   console.log(`  ${dim(`${parts.join(', ')} → ${outDir}`)}`)
   console.log('')
-  console.log(`  Run ${cyan('pnext start')} to serve the production build.`)
-  console.log(`  ${cyan('pnext analyze')} to analyze the build.`)
+  console.log(`  Serve the production build: ${cyan('pnext start')}`)
+  console.log(`  Analyze the build: ${cyan('pnext analyze')}`)
 }
 
 function staticMetadataSummaryFiles(staticFiles: Record<string, StaticFileMetadata>) {

package/src/cli/dev.ts

@@ -125,16 +125,11 @@ function watchEsbuildMemory() {
       ),
     )
     void (async () => {
-      try {
-        const esbuild = await import('esbuild')
-        await esbuild.stop()
-      } catch {
-        // ignore: the service may already be gone
-      }
-      // stop() can strand in-flight build promises unsettled; fail their
-      // waiters so requests retry against the respawned service.
-      const { failInFlightClientBuilds } = await import('../dev/server')
-      failInFlightClientBuilds('esbuild service restarted by the memory watchdog')
+      // The idle-guarded stop: a raw esbuild.stop() under an in-flight compile
+      // fails that request with a 500, so a busy service drains first. In-flight
+      // builds are untouched, so their waiters must not be failed here.
+      const { stopEsbuildService } = await import('../utils/esbuild')
+      stopEsbuildService()
     })()
   }, 15_000)
   timer.unref()

package/src/cli/migrate/package-json.ts

@@ -147,7 +147,7 @@ export async function migratePackageJson(
   if (leftovers.length > 0) {
     result.reports.push({
       title: 'Next-specific packages still installed',
-      detail: 'Optional cleanup — these are unused under pnext. See reference/compat.md.',
+      detail: 'Optional cleanup — these are unused under pnext. See https://pnext.dev/docs/compat.',
       files: leftovers,
     })
   }

package/src/cli/migrate/report.ts

@@ -25,10 +25,12 @@ export interface ReportItem {
 export interface MigrationResult {
   edits: Edit[]
   reports: ReportItem[]
+  /** Files reading cookies()/headers()/draftMode() synchronously (Next 14 style). */
+  syncRequestApis: string[]
 }
 
 export function emptyResult(): MigrationResult {
-  return { edits: [], reports: [] }
+  return { edits: [], reports: [], syncRequestApis: [] }
 }
 
 export function printHeader(root: string, dryRun: boolean) {
@@ -63,8 +65,8 @@ export function printResult(result: MigrationResult, options: { install: string
   }
 
   lines.push(`\n${bold('Next steps')}`)
-  lines.push(`  Run ${cyan(options.install)} to install the new dependencies.`)
-  lines.push(`  ${cyan('pnext dev')} to start the app.`)
+  lines.push(`  1. Install the new dependencies: ${cyan(options.install)}`)
+  lines.push(`  2. Start the app: ${cyan('pnext dev')}`)
   console.log(lines.join('\n'))
 }
 

package/src/cli/migrate/run.ts

@@ -37,32 +37,58 @@ export async function migrateApp(directory: string | undefined, options: { dryRu
   printHeader(root, options.dryRun)
   const result = emptyResult()
   if (pkg) await migratePackageJson(root, pkg, result, options.dryRun)
+  // The scan runs first: what it finds (sync request APIs) decides what the config enables.
+  await withSpinner('Scanning sources ...', () => scanSources(root, result))
   await createPnextConfig(root, result, options.dryRun)
   await migrateTsconfig(root, result, options.dryRun)
   await removeNextEnv(root, result, options.dryRun)
   await updateGitignore(root, result, options.dryRun)
-  await withSpinner('Scanning sources ...', () => scanSources(root, result))
 
   printResult(result, { install: installCommand(root) })
   return 0
 }
 
 async function createPnextConfig(root: string, result: MigrationResult, dryRun: boolean) {
+  const legacy = result.syncRequestApis.length > 0
   const existing = PNEXT_CONFIG_FILES.find(name => existsSync(path.join(root, name)))
   if (existing) {
     result.reports.push({
       title: `${existing} already exists`,
-      detail: 'Make sure it sets compat: { next: true }. See reference/compat.md.',
+      detail: 'Make sure it sets compat: { next: true }. See https://pnext.dev/docs/compat.',
     })
+    if (legacy) reportSyncRequestApis(result, existing)
     return
   }
   if (!dryRun) {
     await writeFile(
       path.join(root, 'pnext.config.ts'),
-      'export default { compat: { next: true } };\n',
+      legacy
+        ? 'export default {\n' +
+            '  compat: {\n' +
+            '    // Sync cookies()/headers() still work; migrate to `await` and drop this.\n' +
+            '    next: { legacyRequestAPIs: true },\n' +
+            '  },\n' +
+            '};\n'
+        : 'export default { compat: { next: true } };\n',
     )
   }
-  result.edits.push({ file: 'pnext.config.ts', description: 'created with compat.next enabled' })
+  result.edits.push({
+    file: 'pnext.config.ts',
+    description: legacy
+      ? 'created with compat.next enabled (legacyRequestAPIs)'
+      : 'created with compat.next enabled',
+  })
+  if (legacy) reportSyncRequestApis(result)
+}
+
+function reportSyncRequestApis(result: MigrationResult, existingConfig?: string) {
+  result.reports.push({
+    title: 'Sync cookies()/headers() 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',
+    files: [...new Set(result.syncRequestApis)],
+  })
 }
 
 async function removeNextEnv(root: string, result: MigrationResult, dryRun: boolean) {

package/src/cli/migrate/scan.ts

@@ -17,6 +17,11 @@ const LOADERS: Record<string, 'ts' | 'tsx' | 'js' | 'jsx'> = {
   '.cjs': 'js',
 }
 const STREAMING_APIS = ['renderToReadableStream', 'renderToPipeableStream']
+// `cookies().get(...)` / `headers()['x']` with no `await` — Next 14 sync request-API reads.
+const CALL_THEN_ACCESS = /(await\s+)?\b([\w$]+)\s*\(\s*\)\s*(?:\.\s*([\w$]+)|\[)/g
+const NEXT_HEADERS_IMPORT = /import\s*\{([^}]*)\}\s*from\s*['"]next\/headers['"]/g
+const REQUEST_APIS = new Set(['cookies', 'headers', 'draftMode'])
+const PROMISE_METHODS = new Set(['then', 'catch', 'finally'])
 const SPECIAL_PAGES = ['_app', '_document', '_error']
 
 export async function scanSources(root: string, result: MigrationResult) {
@@ -49,13 +54,14 @@ export async function scanSources(root: string, result: MigrationResult) {
       }
       if (specifier === 'next/head') headImports.push(relative)
     }
+    if (readsRequestApiSynchronously(text)) result.syncRequestApis.push(relative)
   }
 
   if (deepImports.length > 0) {
     result.reports.push({
       title: 'Unsupported next/dist/* deep imports',
       detail:
-        'Only five next/dist paths are shimmed — replace these with public APIs. See reference/compat.md ("Smaller surfaces").',
+        'Only five next/dist paths are shimmed — replace these with public APIs. See https://pnext.dev/docs/compat ("Smaller surfaces").',
       files: deepImports,
     })
   }
@@ -63,16 +69,16 @@ export async function scanSources(root: string, result: MigrationResult) {
     result.reports.push({
       title: 'react-dom/server streaming APIs',
       detail:
-        'preact/compat does not provide renderToReadableStream/renderToPipeableStream — use pnext rendering instead. See reference/compat.md.',
+        'preact/compat does not provide renderToReadableStream/renderToPipeableStream — use pnext rendering instead. See https://pnext.dev/docs/compat.',
       files: [...new Set(streaming)],
     })
   }
 
   if (headImports.length > 0) {
     result.reports.push({
-      title: 'next/head renders nothing',
+      title: 'next/head is ignored in the app router',
       detail:
-        'Move these tags to metadata exports (or the root layout <head>) — next/head is a silent no-op under pnext. See reference/compat.md.',
+        'pnext ignores next/head in app-directory components (matching Next). Move these tags to metadata exports or the root layout <head>. See https://pnext.dev/docs/compat.',
       files: [...new Set(headImports)],
     })
   }
@@ -81,6 +87,27 @@ export async function scanSources(root: string, result: MigrationResult) {
   await scanNextConfig(root, result)
 }
 
+/**
+ * A next/headers request API called and immediately read, with no `await` — the Next 14 shape that
+ * throws under Next 16 semantics. Local aliases (`cookies as getCookies`) count; `.then()` chains do not.
+ */
+function readsRequestApiSynchronously(text: string): boolean {
+  const locals = new Set<string>()
+  for (const match of text.matchAll(NEXT_HEADERS_IMPORT)) {
+    for (const binding of match[1]!.split(',')) {
+      const [imported, local] = binding.trim().split(/\s+as\s+/)
+      if (imported && REQUEST_APIS.has(imported)) locals.add(local ?? imported)
+    }
+  }
+  if (locals.size === 0) return false
+  for (const match of text.matchAll(CALL_THEN_ACCESS)) {
+    if (match[1] || !locals.has(match[2]!)) continue
+    if (match[3] && PROMISE_METHODS.has(match[3])) continue
+    return true
+  }
+  return false
+}
+
 function scanSpecialPages(root: string, result: MigrationResult) {
   const found: string[] = []
   for (const base of ['pages', path.join('src', 'pages')]) {
@@ -95,7 +122,7 @@ function scanSpecialPages(root: string, result: MigrationResult) {
   result.reports.push({
     title: 'pages/_app, _document and _error are ignored',
     detail:
-      'Move this setup into the app-router root layout — pnext never loads these files. See reference/compat.md.',
+      'Move this setup into the app-router root layout — pnext never loads these files. See https://pnext.dev/docs/compat.',
     files: found,
   })
 }
@@ -110,8 +137,8 @@ async function scanNextConfig(root: string, result: MigrationResult) {
     result.reports.push({
       title: `${name} defines a webpack function`,
       detail: svgr
-        ? 'The webpack function is never executed; SVGR is auto-detected from @svgr/webpack, so SVG imports keep working. See reference/compat.md.'
-        : 'The webpack function is never executed — port any custom loaders/plugins to pnext config. See reference/compat.md.',
+        ? 'The webpack function is never executed; SVGR is auto-detected from @svgr/webpack, so SVG imports keep working. See https://pnext.dev/docs/compat.'
+        : 'The webpack function is never executed — port any custom loaders/plugins to pnext config. See https://pnext.dev/docs/compat.',
     })
     return
   }

package/src/cli/typegen.ts

@@ -145,7 +145,14 @@ function paramsType(route: RouteManifestEntry) {
 }
 
 async function writeIfChanged(file: string, source: string) {
-  if (existsSync(file) && (await readFile(file, 'utf8')) === source) return
+  // A concurrent typegen (the dev server runs one off the critical path, a CLI run can overlap it
+  // on the same out-dir) can delete the file between the existence check and the read; a failed
+  // read just means "changed", never a crash.
+  try {
+    if (existsSync(file) && (await readFile(file, 'utf8')) === source) return
+  } catch {
+    // fall through to the write
+  }
   await ensureDir(path.dirname(file))
   await writeFile(file, source)
 }

package/src/client/build.ts

@@ -56,6 +56,7 @@ import { clientReferenceId, ssrClientReference, type ClientReference } from './r
 import { shouldReactCompile, transformReactCompiler } from './react-compiler'
 import { createVerboseLogger, formatDuration } from '../utils/verbose'
 import { dim as dimText } from '../utils/ansi'
+import { traceEnabled } from '../utils/trace-flags'
 import type { RouteManifestEntry } from '../types'
 import {
   applyClientSourceAsyncPreTransforms,
@@ -1016,7 +1017,7 @@ function deploymentIdDefine(): Record<string, string> {
  * Wrap every plugin's onResolve/onLoad so the profile reports, per plugin, how
  * many callbacks esbuild made and how long they held the JS thread. Each call
  * is an IPC round trip, so the counts are what distinguishes "our transforms are
- * slow" from "we are answering 40k questions". Off unless PNEXT_CLIENT_PROFILE.
+ * slow" from "we are answering 40k questions". Off unless PNEXT_TRACE=client.
  */
 function instrumentedPlugins(plugins: Plugin[]): Plugin[] {
   if (!clientProfile.enabled) return plugins
@@ -1657,8 +1658,7 @@ async function profileClientBuild<T>(
   dev: boolean | undefined,
   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()
@@ -2075,8 +2075,7 @@ function rootFromFile(file: string) {
 // the metafile: the package name for node_modules code, the file stem for app
 // code. Falls back to "shared" when a build ran without a metafile.
 async function nameSharedClientChunks(outDir: string, metafile?: Metafile) {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (metafile && process.env.PNEXT_CLIENT_METAFILE) {
+  if (metafile && traceEnabled('client')) {
     await writeText(path.join(outDir, 'metafile.json'), JSON.stringify(metafile))
   }
   const chunksDir = path.join(outDir, 'chunks')

package/src/client/profile.ts

@@ -1,8 +1,9 @@
 // Phase decomposition for the client stage (read / transform / react-compiler /
-// esbuild / write), off unless PNEXT_CLIENT_PROFILE is set. The bench needs the
+// esbuild / write), off unless PNEXT_TRACE=client. The bench needs the
 // split to prove where the residual sits; a build must not pay for it.
-// eslint-disable-next-line turbo/no-undeclared-env-vars
-const enabled = Boolean(process.env.PNEXT_CLIENT_PROFILE)
+import { traceEnabled } from '../utils/trace-flags'
+
+const enabled = traceEnabled('client')
 
 const totals = new Map<string, number>()
 const spans = new Map<string, [number, number][]>()

package/src/client/router/runtime.ts

@@ -5138,7 +5138,11 @@ export function onPopState() {
 }
 
 const eagerLinks = new WeakSet<Element>()
+// Per DOCUMENT, not per process: an observer belongs to the document whose links it watches.
+// A browser page never swaps documents, but multi-document hosts (jsdom embedders, the test
+// process) do, and a stale observer silently never fires for the new document's links.
 let visibleLinkObserver: IntersectionObserver | undefined
+let visibleLinkObserverDoc: Document | undefined
 
 // `load` links prefetch as soon as they appear; `visible` links when they
 // enter the viewport. Both arrive with the page or with later client renders,
@@ -5168,6 +5172,10 @@ function scanEagerPrefetchLinks(root: Element) {
       if (href) void prefetchRoute(href, { element: link, full: isFullPrefetchLink(link) })
       continue
     }
+    if (visibleLinkObserverDoc !== document) {
+      visibleLinkObserver = undefined
+      visibleLinkObserverDoc = document
+    }
     visibleLinkObserver ??= new IntersectionObserver(entries => {
       for (const entry of entries) {
         if (!entry.isIntersecting) {

package/src/compat/actions/config.ts

@@ -22,6 +22,8 @@ export interface NextConfigShape {
   experimental?: { serverActions?: { bodySizeLimit?: unknown } | boolean }
   rewrites?: () => unknown
   redirects?: () => unknown
+  headers?: () => unknown
+  poweredByHeader?: boolean
 }
 
 export async function loadServerActionsConfig(root: string): Promise<ServerActionsConfig> {

package/src/compat/aliases.ts

@@ -22,7 +22,7 @@ export function nextCompatEnabled(config: CompatConfig) {
   return Boolean(config.compat?.next)
 }
 
-/** The only `next/dist/*` deep imports pnext shims (see reference/compat.md "Smaller surfaces"). */
+/** The only `next/dist/*` deep imports pnext shims (see https://pnext.dev/docs/compat "Smaller surfaces"). */
 export const SHIMMED_NEXT_DIST_PATHS = [
   'next/dist/client/components/app-router-headers',
   'next/dist/server/web/spec-extension/unstable-cache',
@@ -50,7 +50,7 @@ export function missingCompatImportError(
           `'${specifier}' is not a supported import: next/dist internals are not part of the ` +
           `public surface pnext shims. Only these next/dist/* paths are shimmed:\n` +
           SHIMMED_NEXT_DIST_PATHS.map(path => `  - ${path}`).join('\n') +
-          `\nSee reference/compat.md ("Smaller surfaces") and report the library that needs a new shim.`
+          `\nSee https://pnext.dev/docs/compat ("Smaller surfaces") and report the library that needs a new shim.`
         )
       }
     }

package/src/compat/bundler/react-profiler.tsx

@@ -1,3 +1,4 @@
+/** @jsxImportSource preact */
 import { Fragment, type ComponentChildren } from 'preact'
 import { useLayoutEffect, useRef } from 'preact/hooks'