@wular/pnext 0.0.2 → 0.0.4

package/src/resolve/scan-facts.ts

@@ -10,7 +10,11 @@
 // The same parse also backs `rewriteFacts`: the record-shaped rewrite passes (specifier aliasing, namespace
 // imports, import.meta.url) splice byte spans off it instead of re-scanning the source with their own
 // regexes.
-import { parseSync } from 'oxc-parser';
+// 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 { spliceSource } from '../dev/module-transform';
 
 export interface ScanEdge {
@@ -71,6 +75,33 @@ export interface RewriteFacts {
   unreliable: boolean;
 }
 
+/**
+ * A `name(loader, options?)` call whose loader statically targets one module —
+ * the shape `dynamic()` extraction needs. Emitted for every identifier-callee
+ * call with such a loader; consumers gate on their own `dynamic` binding set.
+ */
+export interface DynamicCallFact {
+  name: string;
+  /** Callee identifier start — aligns with the textual call scan's index. */
+  start: number;
+  /** Call end (past the closing paren). */
+  end: number;
+  /** Loader target, cooked value. */
+  specifier: string;
+  /** Span of the quoted specifier literal, quotes included. */
+  specifierStart: number;
+  specifierEnd: number;
+  /** From the `.then(m => m.X)` arm (or awaited member); `default` otherwise. */
+  exportName: string;
+  /** First arg is a string literal (`dynamic('./x')` form), not a loader fn. */
+  literal?: boolean;
+  /** End of the loader argument — options/appended args follow it. */
+  loaderEnd: number;
+  /** Second-argument span, when present. */
+  optionsStart?: number;
+  optionsEnd?: number;
+}
+
 export interface ScanFacts {
   /** Static value imports and `export … from` re-exports, in source order. */
   imports: ScanEdge[];
@@ -84,6 +115,8 @@ export interface ScanFacts {
   exportStars: string[];
   /** A real `'use client'` directive — prologue position only, never a comment. */
   useClient: boolean;
+  /** Loader-shaped calls (see `DynamicCallFact`); only sources that can bind `dynamic` are walked. */
+  dynamicCalls: DynamicCallFact[];
 }
 
 const stylesheetOrData = /\.(?:css|scss|sass|less|styl|json)$/;
@@ -95,6 +128,7 @@ const emptyFacts: ScanFacts = {
   exportNames: [],
   exportStars: [],
   useClient: false,
+  dynamicCalls: [],
 };
 
 const emptyRewriteFacts: RewriteFacts = {
@@ -134,6 +168,15 @@ export function moduleExportStars(source: string, sourcefile = 'source.tsx') {
   return scanFacts(sourcefile, source).exportStars;
 }
 
+/**
+ * AST-derived `dynamic()` loader facts — the single source of truth. A call
+ * without a fact is an unanalyzable loader: no detection, nothing to splice.
+ */
+export function dynamicCallFacts(source: string, file = 'module.tsx'): DynamicCallFact[] {
+  if (stylesheetOrData.test(file)) return [];
+  return parsed(file, source).scan.dynamicCalls;
+}
+
 /** Module-record spans for the rewrite passes (see `RewriteFacts`). */
 export function rewriteFacts(file: string, source: string): RewriteFacts {
   if (stylesheetOrData.test(file)) return emptyRewriteFacts;
@@ -323,6 +366,12 @@ function parseFacts(file: string, source: string, lang: ParserLang) {
       exportNames,
       exportStars,
       useClient: hasUseClient(source, result),
+      // `result.program` deserializes the whole AST: walk it only for sources
+      // that can bind `dynamic()` at all (same cheap gate as dynamic/source.ts).
+      dynamicCalls:
+        source.includes('@wular/pnext') || source.includes('next/dynamic')
+          ? collectDynamicCalls(result.program as unknown as AstNode)
+          : [],
     },
     rewrite: {
       edges,
@@ -465,6 +514,195 @@ function literalSpecifier(raw: string) {
   return /^\s*(['"])([^'"]*)\1\s*$/.exec(raw)?.[2] || undefined;
 }
 
+interface AstNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+
+function isNode(value: unknown): value is AstNode {
+  return typeof value === 'object' && value !== null && typeof (value as AstNode).type === 'string';
+}
+
+function child(node: AstNode | undefined, key: string): AstNode | undefined {
+  const value = node?.[key];
+  return isNode(value) ? value : undefined;
+}
+
+function collectDynamicCalls(program: AstNode): DynamicCallFact[] {
+  const calls: DynamicCallFact[] = [];
+  const visit = (value: unknown) => {
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    if (!isNode(value)) return;
+    if (value.type === 'CallExpression') {
+      const fact = dynamicCallFact(value);
+      if (fact) calls.push(fact);
+    }
+    for (const key in value) {
+      if (key === 'type' || key === 'loc' || key === 'range') continue;
+      const entry = value[key];
+      if (entry && typeof entry === 'object') visit(entry);
+    }
+  };
+  visit(program.body);
+  return calls.sort((a, b) => a.start - b.start);
+}
+
+function dynamicCallFact(call: AstNode): DynamicCallFact | undefined {
+  const callee = child(call, 'callee');
+  if (callee?.type !== 'Identifier') return undefined;
+  const args = call.arguments;
+  if (!Array.isArray(args) || !isNode(args[0])) return undefined;
+  const loader = args[0];
+
+  let target: { specifier: AstNode; exportName: string } | undefined;
+  let literal: boolean | undefined;
+  if (stringValue(loader) !== undefined) {
+    target = { specifier: loader, exportName: 'default' };
+    literal = true;
+  } else if (loader.type === 'ArrowFunctionExpression' || loader.type === 'FunctionExpression') {
+    target = loaderImportTarget(loader) ?? firstImportTarget(loader);
+  }
+  if (!target) return undefined;
+
+  const specifier = stringValue(target.specifier);
+  if (specifier === undefined) return undefined;
+  const options = isNode(args[1]) ? args[1] : undefined;
+  return {
+    name: callee.name as string,
+    start: callee.start,
+    end: call.end,
+    specifier,
+    specifierStart: target.specifier.start,
+    specifierEnd: target.specifier.end,
+    exportName: target.exportName,
+    ...(literal ? { literal } : {}),
+    loaderEnd: loader.end,
+    ...(options ? { optionsStart: options.start, optionsEnd: options.end } : {}),
+  };
+}
+
+function stringValue(node: AstNode | undefined): string | undefined {
+  if (!node) return undefined;
+  if (node.type !== 'Literal' && node.type !== 'StringLiteral') return undefined;
+  return typeof node.value === 'string' ? node.value : undefined;
+}
+
+/** Past parens, `await`, `as`/`!` and optional-chain wrappers to the loader's real expression. */
+function unwrapExpression(node: AstNode | undefined): AstNode | undefined {
+  let current = node;
+  for (;;) {
+    if (!current) return undefined;
+    if (current.type === 'ParenthesizedExpression' || current.type === 'ChainExpression') {
+      current = child(current, 'expression');
+    } else if (current.type === 'AwaitExpression') {
+      current = child(current, 'argument');
+    } else if (current.type === 'TSAsExpression' || current.type === 'TSNonNullExpression' || current.type === 'TSSatisfiesExpression') {
+      current = child(current, 'expression');
+    } else {
+      return current;
+    }
+  }
+}
+
+/** The expression a loader function resolves to: its expression body or first `return`. */
+function loaderResult(fn: AstNode): AstNode | undefined {
+  const body = child(fn, 'body');
+  if (!body) return undefined;
+  if (body.type !== 'BlockStatement' && body.type !== 'FunctionBody') return unwrapExpression(body);
+  const statements = body.body;
+  if (!Array.isArray(statements)) return undefined;
+  for (const statement of statements) {
+    if (isNode(statement) && statement.type === 'ReturnStatement') {
+      return unwrapExpression(child(statement, 'argument'));
+    }
+  }
+  return undefined;
+}
+
+function importSource(node: AstNode | undefined): AstNode | undefined {
+  if (node?.type !== 'ImportExpression') return undefined;
+  const source = child(node, 'source');
+  return source && stringValue(source) !== undefined ? source : undefined;
+}
+
+/**
+ * Statically resolve a loader body: `import('x')`, `import('x').then(m => m.X)`
+ * (any param/arrow formatting), or `(await import('x')).X`.
+ */
+function loaderImportTarget(fn: AstNode): { specifier: AstNode; exportName: string } | undefined {
+  const result = loaderResult(fn);
+  if (!result) return undefined;
+
+  const direct = importSource(result);
+  if (direct) return { specifier: direct, exportName: 'default' };
+
+  if (result.type === 'MemberExpression' && result.computed !== true) {
+    const source = importSource(unwrapExpression(child(result, 'object')));
+    const property = child(result, 'property');
+    if (source && property?.type === 'Identifier') {
+      return { specifier: source, exportName: property.name as string };
+    }
+  }
+
+  if (result.type !== 'CallExpression') return undefined;
+  const callee = child(result, 'callee');
+  if (callee?.type !== 'MemberExpression' || callee.computed === true) return undefined;
+  if (child(callee, 'property')?.name !== 'then') return undefined;
+  const source = importSource(unwrapExpression(child(callee, 'object')));
+  if (!source) return undefined;
+  return { specifier: source, exportName: thenArmExport(result) ?? 'default' };
+}
+
+/** `X` of a `.then(m => m.X)` arm; undefined for any other arm shape. */
+function thenArmExport(thenCall: AstNode): string | undefined {
+  const args = thenCall.arguments;
+  if (!Array.isArray(args) || !isNode(args[0])) return undefined;
+  const arm = args[0];
+  if (arm.type !== 'ArrowFunctionExpression' && arm.type !== 'FunctionExpression') return undefined;
+  const params = arm.params;
+  const param = Array.isArray(params) && isNode(params[0]) ? params[0] : undefined;
+  if (param?.type !== 'Identifier') return undefined;
+  const result = loaderResult(arm);
+  if (result?.type !== 'MemberExpression' || result.computed === true) return undefined;
+  const object = unwrapExpression(child(result, 'object'));
+  if (object?.type !== 'Identifier' || object.name !== param.name) return undefined;
+  const property = child(result, 'property');
+  return property?.type === 'Identifier' ? (property.name as string) : undefined;
+}
+
+/**
+ * Fallback for loader shapes the structured pass cannot follow: the first
+ * literal `import()` anywhere in the loader, default export — mirrors what the
+ * textual extraction always did for these.
+ */
+function firstImportTarget(fn: AstNode): { specifier: AstNode; exportName: string } | undefined {
+  let found: AstNode | undefined;
+  const visit = (value: unknown) => {
+    if (found) return;
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    if (!isNode(value)) return;
+    const source = importSource(value);
+    if (source) {
+      found = source;
+      return;
+    }
+    for (const key in value) {
+      const entry = value[key];
+      if (entry && typeof entry === 'object') visit(entry);
+    }
+  };
+  visit(fn.body);
+  return found ? { specifier: found, exportName: 'default' } : undefined;
+}
+
 type ParserLang = 'ts' | 'tsx';
 
 // `.ts` forbids JSX (`<T>value` is a type assertion there); everything else —

package/src/routing/href.ts

@@ -28,14 +28,13 @@ declare global {
 // once per process by the server runtime from the resolved config. On the
 // client the value is read from the injected window global (register-render's
 // trailingSlashScript), mirroring basePath / skipTrailingSlash.
-let trailingSlashUrls = false;
-
+// Anchored on globalThis, not a module local: this module is dual-copied into
+// the client/prebundled bundles, where setTrailingSlashUrls never runs.
 export function setTrailingSlashUrls(enabled: boolean) {
-  trailingSlashUrls = enabled;
+  globalThis.__PNEXT_TRAILING_SLASH__ = enabled;
 }
 
 function isTrailingSlashEnabled(): boolean {
-  if (trailingSlashUrls) return true;
   if (process.browser || typeof window !== 'undefined') return window.__PNEXT_TRAILING_SLASH__ === true;
   return globalThis.__PNEXT_TRAILING_SLASH__ === true;
 }
@@ -76,7 +75,7 @@ export function withBasePath(path: string) {
 export function applyTrailingSlash(pathname: string) {
   const [, path = '', rest = ''] = /^([^?#]*)([\s\S]*)$/.exec(pathname) ?? [];
   if (!path.startsWith('/')) return pathname;
-  if (trailingSlashUrls) {
+  if (isTrailingSlashEnabled()) {
     // Add the canonical trailing slash (skip root, already-slashed, and files).
     if (path === '/' || path.endsWith('/') || /\.[^/]+$/.test(path)) return pathname;
     return `${path}/${rest}`;

package/src/routing/routes.ts

@@ -15,7 +15,7 @@ import {
   resolveModuleAlias,
   resolvePackageSpecifier,
 } from '../resolve/imports';
-import { scanFacts } from '../resolve/scan-facts';
+import { dynamicCallFacts, scanFacts, type DynamicCallFact } from '../resolve/scan-facts';
 import { readSourceSync } from '../resolve/source-text';
 import { globalCssSourcesForPaths } from '../css';
 import {
@@ -340,7 +340,11 @@ export function setRouteFactsStore(store: RouteFactsStore | undefined) {
   factsStore = store;
 }
 
-function withDeferredFacts(base: RoutePathEntry, compute: () => RouteFacts): RouteManifestEntry {
+function withDeferredFacts(
+  appPath: string,
+  base: RoutePathEntry,
+  compute: () => RouteFacts,
+): RouteManifestEntry {
   const entry = base as RouteManifestEntry;
   let facts: RouteFacts | undefined;
   // Consumers still assign some of these (the build marks needsRouterEntry), so
@@ -355,7 +359,10 @@ function withDeferredFacts(base: RoutePathEntry, compute: () => RouteFacts): Rou
       get() {
         if (overrides.has(field)) return overrides.get(field);
         if (!facts) {
-          const key = `${base.kind}:${base.id}`;
+          // Route ids repeat across apps ('page:/' everywhere), so the app the
+          // facts were derived in is part of the key - otherwise one app's
+          // record answers another app's lookup in the same process.
+          const key = `${appPath}\0${base.kind}:${base.id}`;
           const stored = factsStore?.load(key);
           facts = stored ?? withDirCache(compute);
           if (!stored) factsStore?.save(key, facts);
@@ -415,6 +422,7 @@ function buildRouteTable(appPath: string, files: string[]): RouteManifestEntry[]
       if (!metadataParts) continue;
       routes.push(
         withDeferredFacts(
+          appPath,
           {
             id: `metadata-${routeId(metadataParts.route)}`,
             kind: 'handler',
@@ -462,6 +470,7 @@ function buildRouteTable(appPath: string, files: string[]): RouteManifestEntry[]
     const interception = parts.interception;
     routes.push(
       withDeferredFacts(
+        appPath,
         {
           id: interception ? `intercept-${sanitizeIdPart(routeDir)}` : routeId(parts.route || '/'),
           kind,
@@ -844,6 +853,7 @@ function appendSlotDerivedRoutes(
       // interceptor during slot rendering. Kept minimal on purpose.
       routes.push(
         withDeferredFacts(
+          appPath,
           {
             id: `intercept-${sanitizeIdPart(candidate.relative.replace(pageOrRouteTrailing(), ''))}`,
             kind: 'page',
@@ -905,6 +915,7 @@ function appendSlotDerivedRoutes(
 
     routes.push(
       withDeferredFacts(
+        appPath,
         {
           id: `slot-${routeId(parts.route || '/')}`,
           kind: 'page',
@@ -1050,6 +1061,7 @@ function appendDefaultDerivedRoutes(
 
     routes.push(
       withDeferredFacts(
+        appPath,
         {
           id: `default-${routeId(parts.route || '/')}`,
           kind: 'page',
@@ -2264,21 +2276,14 @@ function dynamicImportEdgesFromSource(
   if (dynamicNames.size === 0) return imports;
 
   const optionObjects = dynamicOptionObjects(source);
-  const dynamicPattern =
-    /import\s*\(\s*['"]([^'"]+)['"]\s*\)(?:\s*\.then\s*\(\s*([A-Za-z_$][\w$]*)\s*=>\s*\2\.([A-Za-z_$][\w$]*)\s*\))?/g;
-  let match: RegExpExecArray | null;
-
-  while ((match = dynamicPattern.exec(source))) {
-    const [, specifier, _moduleName, exportName] = match;
-    if (!specifier) continue;
-    if (!isDynamicCallImport(source, match.index, dynamicNames)) continue;
-
-    const resolved = resolveModuleEdge(root, file, specifier);
+  for (const fact of dynamicCallFacts(source, file)) {
+    if (!dynamicNames.has(fact.name)) continue;
+    const resolved = resolveModuleEdge(root, file, fact.specifier);
     if (!resolved) continue;
     imports.push({
       file: resolved,
-      exports: [exportName ?? 'default'],
-      dynamic: dynamicOptionsForImport(source, dynamicPattern.lastIndex, optionObjects),
+      exports: [fact.exportName],
+      dynamic: dynamicOptionsForFact(source, fact, optionObjects),
     });
   }
 
@@ -2298,35 +2303,15 @@ function dynamicOptionObjects(source: string) {
   return options;
 }
 
-function isDynamicCallImport(source: string, importIndex: number, dynamicNames: Set<string>) {
-  const prefix = source.slice(Math.max(0, importIndex - 120), importIndex);
-  const dynamicIndex = nextDynamicCallIndexFromEnd(prefix, dynamicNames);
-  if (dynamicIndex === -1) return false;
-  return !/[;\n]\s*$/.test(prefix.slice(dynamicIndex));
-}
-
-function nextDynamicCallIndexFromEnd(source: string, dynamicNames: Set<string>) {
-  let next = -1;
-  for (const name of dynamicNames) {
-    const index = source.lastIndexOf(name);
-    if (index !== -1 && index > next) next = index;
-  }
-  return next;
-}
-
-function dynamicOptionsForImport(
+function dynamicOptionsForFact(
   source: string,
-  endIndex: number,
+  fact: DynamicCallFact,
   optionObjects: Map<string, ClientDynamicReference>,
 ) {
-  const tail = source.slice(endIndex, endIndex + 300);
-  const inlineMatch = /^\s*,\s*({[\s\S]*?})\s*,?\s*\)/.exec(tail);
-  if (inlineMatch?.[1]) return dynamicOptionsFromSource(inlineMatch[1]);
-
-  const identifierMatch = /^\s*,\s*([A-Za-z_$][\w$]*)\s*,?\s*\)/.exec(tail);
-  if (identifierMatch?.[1]) return optionObjects.get(identifierMatch[1]) ?? {};
-
-  return {};
+  if (fact.optionsStart === undefined || fact.optionsEnd === undefined) return {};
+  const options = source.slice(fact.optionsStart, fact.optionsEnd);
+  if (/^[A-Za-z_$][\w$]*$/.test(options)) return optionObjects.get(options) ?? {};
+  return dynamicOptionsFromSource(options);
 }
 
 function dynamicOptionsFromSource(source?: string): ClientDynamicReference {

package/src/runtime/server.ts

@@ -4,7 +4,8 @@ import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { copyFile, mkdir, readFile, rm, stat, symlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { build, transform, type Loader, type Metafile, type OnLoadResult, type OnResolveResult, type Plugin } from 'esbuild';
+import type { Loader, Metafile, OnLoadResult, OnResolveResult, Plugin } from 'esbuild';
+import { build, transform } from '../utils/esbuild';
 import {
   applyBundledSourceTransforms,
   applyServerSourcePreTransforms,
@@ -2836,9 +2837,12 @@ async function bundleExternalPackageImpl(
     resolvedEntry?.match(/\.[cm]?tsx?$/) &&
     !getExternalPackagePolicy().transpile(packageName)
   ) {
-    throw new Error(
-      `${path.relative(config.root, resolvedEntry)}\nModule parse failed: Unexpected token`,
-    );
+    const parseFailure = `${path.relative(config.root, resolvedEntry)}\nModule parse failed: Unexpected token`;
+    // Printed directly as well: the digest log path inspects the error's stack,
+    // which some runtimes emit without the message - the CLI output must always
+    // carry the parse failure (Next's transpilePackages error contract).
+    console.error(`⨯ Error: ${parseFailure}`);
+    throw new Error(parseFailure);
   }
   const entry =
     requiredEntry ??

package/src/runtime/vendor.ts

@@ -37,7 +37,7 @@ import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { copyFile, mkdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { build } from 'esbuild';
+import { build } from '../utils/esbuild';
 import { isCommonJsModuleSource } from '../resolve/imports';
 import { outputSpecifiers } from '../dev/module-transform';
 import { escapeRegex, isIdentifier, uniqueIdentifier } from '../utils/source';

package/src/typegen.ts

@@ -25,7 +25,7 @@ export async function writeTypegen(
   allRoutes: RouteManifestEntry[],
 ): Promise<TypegenResult> {
   const routes = allRoutes.filter(route => !route.interception && !route.synthetic);
-  const file = path.join(config.outPath, 'types', 'pnext.gen.d.ts');
+  const file = path.join(config.typesPath, 'pnext.gen.d.ts');
   const source = typegenSource(routes);
   await writeIfChanged(file, source);
   const aliases = await writeRouteAliases(config, routes);
@@ -57,7 +57,7 @@ function routeEntry(route: RouteManifestEntry) {
 }
 
 async function writeChecks(config: ResolvedConfig, routes: RouteManifestEntry[]) {
-  const checksDir = path.join(config.outPath, 'types', 'checks');
+  const checksDir = path.join(config.typesPath, 'checks');
   await rm(checksDir, { recursive: true, force: true });
   await ensureDir(checksDir);
 
@@ -72,7 +72,7 @@ async function writeChecks(config: ResolvedConfig, routes: RouteManifestEntry[])
 }
 
 async function writeRouteAliases(config: ResolvedConfig, routes: RouteManifestEntry[]) {
-  const aliasesDir = path.join(config.outPath, 'types', 'app');
+  const aliasesDir = path.join(config.typesPath, 'app');
   await rm(aliasesDir, { recursive: true, force: true });
   await ensureDir(aliasesDir);
 

package/src/utils/esbuild.ts

@@ -0,0 +1,58 @@
+// Lazy esbuild facade: importing 'esbuild' eagerly costs ~2.7 MB RSS and its
+// first build()/transform() call spawns a resident ~10-45 MB service child, so
+// the library must not load until something actually compiles.
+import type * as Esbuild from 'esbuild';
+import { loadNative } from './native-require';
+
+let esbuild: typeof Esbuild | undefined;
+
+function load(): typeof Esbuild {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return (esbuild ??= loadNative(() => require('esbuild') as typeof Esbuild));
+}
+
+// In-flight compiles, so a stop() never kills the service child out from under
+// one: esbuild drops the pending call's promise and it never settles.
+let inFlight = 0;
+let stopWhenIdle = false;
+
+function track<T>(promise: Promise<T>): Promise<T> {
+  inFlight += 1;
+  return promise.finally(() => {
+    inFlight -= 1;
+    if (inFlight === 0 && stopWhenIdle) {
+      stopWhenIdle = false;
+      void esbuild?.stop();
+    }
+  });
+}
+
+export const build: typeof Esbuild.build = options => track(load().build(options));
+
+export const transform: typeof Esbuild.transform = (input, options) =>
+  track(load().transform(input, options));
+
+/**
+ * Spawn the resident service child ahead of the first real compile. Fire-and-forget: the spawn and
+ * its handshake are subprocess work, so a caller holding wall-clock it does not control (a dev boot,
+ * which compiles nothing before it listens) can absorb a cost the first compile would otherwise pay.
+ */
+export function warmEsbuildService(): void {
+  void transform('', { loader: 'js' }).catch(() => undefined);
+}
+
+/**
+ * Kill the resident esbuild service child (a prod server is done compiling
+ * after its boot config build). No-op when esbuild never loaded; the service
+ * respawns transparently on the next build()/transform() call. Deferred while a
+ * compile is in flight — instrumentation register() bundles concurrently with
+ * server boot, and killing the service mid-build hangs it forever.
+ */
+export function stopEsbuildService(): void {
+  if (!esbuild) return;
+  if (inFlight > 0) {
+    stopWhenIdle = true;
+    return;
+  }
+  void esbuild.stop();
+}

package/src/utils/fs.ts

@@ -92,9 +92,21 @@ export function listFilesSync(root: string): string[] {
   return out;
 }
 
-export async function ensureEmptyDir(dir: string) {
-  await rm(dir, { recursive: true, force: true });
+/** Empty `dir`, leaving the named top-level entries (and their contents) in place. */
+export async function ensureEmptyDir(dir: string, keep: readonly string[] = []) {
+  if (keep.length === 0) {
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    return;
+  }
   await mkdir(dir, { recursive: true });
+  const preserved = new Set(keep);
+  const entries = await readdir(dir).catch(() => [] as string[]);
+  await Promise.all(
+    entries
+      .filter(entry => !preserved.has(entry))
+      .map(entry => rm(path.join(dir, entry), { recursive: true, force: true })),
+  );
 }
 
 export async function ensureDir(dir: string) {

package/src/utils/native-require.ts

@@ -0,0 +1,28 @@
+// Native-binding loader guard.
+//
+// The lazy `require('esbuild' | 'oxc-*' | 'lightningcss')` facades defer a native binding until
+// something actually compiles/parses/resolves - which means the FIRST load can land anywhere, including
+// inside a render the compat edge runtime is wrapping. That runtime swaps a `process` proxy onto
+// globalThis which hides `version`/`versions` (Next parity: user code must not detect Node there), and
+// these loaders read `process.versions.node` / `process.versions.pnp` while initializing - so the
+// require throws. Load them against the real process instead; the module cache then holds a good copy
+// for every later call.
+import realProcess from 'node:process';
+
+export function loadNative<T>(load: () => T): T {
+  const globalObject = globalThis as typeof globalThis & { process?: NodeJS.Process };
+  if (globalObject.process === realProcess) return load();
+  const previous = Object.getOwnPropertyDescriptor(globalObject, 'process');
+  Object.defineProperty(globalObject, 'process', {
+    configurable: true,
+    enumerable: false,
+    writable: true,
+    value: realProcess,
+  });
+  try {
+    return load();
+  } finally {
+    if (previous) Object.defineProperty(globalObject, 'process', previous);
+    else delete (globalObject as { process?: NodeJS.Process }).process;
+  }
+}