@wular/pnext 0.0.2 → 0.0.4

package/src/client/entry.ts

@@ -11,6 +11,8 @@ interface ClientEntryOptions {
   pageFile?: string;
   clientReferences: ClientReference[];
   nextCompat?: boolean;
+  /** See ClientRuntimeFacts.suspense; false drops the Suspense island wrapper (and preact/compat). */
+  suspense?: boolean;
   /**
    * The app reaches a server action anywhere (build's action manifest, or a route whose scan
    * recorded the `actions`/`form` client-entry reason). The whole action client runtime - RPC wire,
@@ -176,13 +178,20 @@ function softRefreshModulePath() {
   return path.join(import.meta.dirname, '../compat/client/errors/soft-refresh.ts');
 }
 
-// The in-tree ClientErrorBoundary is emitted only for a route that has an
-// error.*/not-found.* to render at its own position in the tree. Without one it
-// would only re-throw: the deferred window last resort (errors/install) already
-// drives control-flow errors and mounts global-error for anything uncaught, so
-// an app with no boundary conventions ships none of the boundary cluster.
+function bareErrorBoundaryPath() {
+  return path.join(import.meta.dirname, '../compat/client/errors/bare-boundary.ts');
+}
+
+// The full in-tree ClientErrorBoundary is emitted only for a route that has an
+// error.*/not-found.* to render at its own position in the tree. A route with
+// neither still needs A boundary - a swallowed hydration throw never reaches the
+// window last resort - but only the bare tier, which re-throws and preserves
+// primitive throws for global-error and carries none of the cluster.
 function boundaryImportSource(nextCompat?: boolean, boundary?: boolean, builtinNotFound?: boolean) {
-  if (!nextCompat || !boundary) return '';
+  if (!nextCompat) return '';
+  if (!boundary) {
+    return `import { BareErrorBoundary } from ${JSON.stringify(bareErrorBoundaryPath())};`;
+  }
   return `import { ClientErrorBoundary } from ${JSON.stringify(clientErrorBoundaryPath())};
 import { softRefreshRoute } from ${JSON.stringify(softRefreshModulePath())};${
     builtinNotFound ? `\n${builtInNotFoundSource()}` : ''
@@ -211,6 +220,7 @@ function __PNextBuiltInNotFound() {
 type EntryCompatFacts = Pick<
   ClientEntryOptions,
   | 'nextCompat'
+  | 'suspense'
   | 'actions'
   | 'errorFile'
   | 'globalErrorFile'
@@ -585,14 +595,11 @@ export interface ClientRuntimeFacts {
   deferredIslands?: boolean;
   /** Any island loads on visibility (IntersectionObserver tier). */
   visibleIslands?: boolean;
-  /** Any route has an `error.*`/`not-found.*` the in-tree boundary renders. */
-  errorBoundary?: boolean;
   /**
-   * Some boundary route has NO `not-found.*` of its own, so a client-side
-   * notFound() there falls back to the built-in 404 UI (error-ui.ts). False
-   * keeps that module out of the graph entirely.
+   * Compat runtime must support suspension (Suspense island wrapper, preact/compat). False only when
+   * the app's client graph provably never suspends (see clientCompatSurface); undefined outside compat.
    */
-  builtinNotFound?: boolean;
+  suspense?: boolean;
 }
 
 /** Module specifier the generated route stubs import their runtime from. */
@@ -634,19 +641,19 @@ function dynSharedTableSource(
 }
 
 export function clientRuntimeFacts(
-  routes: { route: RouteFacts; shell?: boolean; boundary?: boolean; notFound?: boolean }[],
+  routes: { route: RouteFacts; shell?: boolean }[],
   nextCompat?: boolean,
+  suspense?: boolean,
 ): ClientRuntimeFacts {
   const references = routes.flatMap(({ route }) => route.clientReferences);
   return {
     nextCompat,
+    suspense: nextCompat ? suspense ?? true : undefined,
     islands: references.length > 0,
     page: routes.some(({ route }) => route.client),
     shell: routes.some(entry => entry.shell),
     deferredIslands: references.some(reference => reference.dynamic?.ssr === false),
     visibleIslands: references.some(reference => reference.dynamic?.load === 'visible'),
-    errorBoundary: routes.some(entry => entry.boundary),
-    builtinNotFound: routes.some(entry => entry.boundary && !entry.notFound),
   };
 }
 
@@ -661,7 +668,8 @@ interface RouteFacts {
  * Route-specific values (islands, the client page, shell layouts, error components) arrive as config.
  */
 export function clientRuntimeSource(facts: ClientRuntimeFacts) {
-  const { nextCompat, deferredIslands, errorBoundary, builtinNotFound, page, shell } = facts;
+  const { nextCompat, deferredIslands, page, shell } = facts;
+  const suspense = nextCompat && facts.suspense !== false;
   // The shell re-renders the whole document through the client root layout, so
   // it revives island DOM exactly like an island mount does.
   const revival = Boolean(facts.islands || shell);
@@ -669,8 +677,7 @@ export function clientRuntimeSource(facts: ClientRuntimeFacts) {
 import { h, hydrate, render } from 'preact';
 ${nextCompat ? "import { options as __pnextPreactOptions } from 'preact';" : ''}
 ${deferredIslands ? "import { useEffect, useState } from 'preact/hooks';" : ''}
-${nextCompat ? "import { Suspense } from 'preact/compat';" : ''}
-${boundaryImportSource(nextCompat, errorBoundary, builtinNotFound)}
+${suspense ? "import { Suspense } from 'preact/compat';" : ''}
 ${revival ? layoutSegmentHelperSource(nextCompat) : ''}
 ${revival ? propsParserSource(nextCompat) : ''}
 ${revival ? islandHelpersSource(facts) : ''}
@@ -685,7 +692,7 @@ export function bootstrapRoute(config) {
   let pnextIslandMounts;
   let pnextIslandScan;
   let pnextVisibleMount;
-${clientBoundaryHelperSource(nextCompat, errorBoundary, builtinNotFound)}
+${clientBoundaryHelperSource(nextCompat, suspense)}
 ${mountSource()}
 ${revival ? hydrateIslandsSource(facts) : ''}
 ${shell ? hydrateClientShellSource(nextCompat) : ''}
@@ -700,6 +707,7 @@ export function clientEntrySource(options: ClientEntryOptions) {
     options;
   const facts: EntryCompatFacts = {
     nextCompat,
+    suspense: options.suspense,
     actions: options.actions,
     errorFile,
     globalErrorFile: options.globalErrorFile,
@@ -765,17 +773,12 @@ ${pageFile ? `import Page from ${JSON.stringify(pageFile)};` : ''}
 ${imports}
 ${dynSharedTableSource(nextCompat, options.deferredDynamicHref)}
 ${routerImportSource(facts)}
+${boundaryImportSource(nextCompat, hasErrorBoundary(facts), !notFoundFile)}
 
 const { mountRoute, remountRoute, unmountRoute } = bootstrapRoute({
   islands: [
   ${islandManifest}
-  ],${pageFile ? '\n  Page,' : ''}${shellNames ? `\n  shell: [${shellNames.join(', ')}],` : ''}${
-    nextCompat
-      ? `\n  errorComponent: ${errorFile ? '__PNextRouteErrorComponent' : 'undefined'},\n  notFoundComponent: ${
-          notFoundFile ? '__PNextRouteNotFoundComponent' : 'undefined'
-        },`
-      : ''
-  }
+  ],${pageFile ? '\n  Page,' : ''}${shellNames ? `\n  shell: [${shellNames.join(', ')}],` : ''}${boundaryConfigSource(facts)}
 });
 export { mountRoute, remountRoute, unmountRoute };
 
@@ -785,6 +788,23 @@ if (window.__PNEXT_REGISTER_ENTRY__) window.__PNEXT_REGISTER_ENTRY__(import.meta
 `;
 }
 
+/**
+ * The `bootstrapRoute` config fields carrying this route's in-tree boundary: the
+ * full tier for a route with an `error`/`not-found` file to render, the bare tier
+ * for one with neither. Emitting it per route is what keeps the cluster out of
+ * the app-wide runtime chunk.
+ */
+function boundaryConfigSource(facts: EntryCompatFacts) {
+  if (!facts.nextCompat) return '';
+  const base = `\n  errorComponent: ${facts.errorFile ? '__PNextRouteErrorComponent' : 'undefined'},\n  notFoundComponent: ${
+    facts.notFoundFile ? '__PNextRouteNotFoundComponent' : 'undefined'
+  },`;
+  if (!hasErrorBoundary(facts)) return `${base}\n  errorBoundary: BareErrorBoundary,`;
+  return `${base}\n  errorBoundary: ClientErrorBoundary,\n  onBoundaryReset: softRefreshRoute,${
+    facts.notFoundFile ? '' : '\n  builtInNotFound: __PNextBuiltInNotFound,'
+  }`;
+}
+
 function shellClientReferences(
   clientReferences: ClientReference[],
   errorFile?: string,
@@ -842,10 +862,11 @@ function visibleDynamicIslandEntrySource(
   }, onReset: softRefreshRoute }, vnode);
 }
 `
-      : // No error.*/not-found.* to render here: the deferred window last resort
-        // owns every client throw, so the boundary collapses to the vnode.
+      : // No error.*/not-found.* to render here: the bare tier only re-throws
+        // (and escalates primitive throws), so the window last resort still owns
+        // the outcome without this route carrying the boundary cluster.
         `function pnextClientBoundary(h, vnode) {
-  return vnode;
+  return h(BareErrorBoundary, null, vnode);
 }
 `;
 
@@ -936,16 +957,14 @@ function mountIsland(root, island) {
 }
 
 async function mountIslandTree(root, island) {
-  const [{ h, hydrate, render }, { Suspense }, Component] = await Promise.all([
-    import('preact'),
-    import('preact/compat'),
+  const [{ h, hydrate, render }${facts.suspense !== false ? ', { Suspense }' : ''}, Component] = await Promise.all([
+    import('preact'),${facts.suspense !== false ? "\n    import('preact/compat')," : ''}
     island.load(),
   ]);
-  islandBoundary = Suspense;
-  const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
+${facts.suspense !== false ? '  islandBoundary = Suspense;\n' : ''}  const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
   const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node)), await staticChildren(h, source, island.id));
-  const wrapped = h(Suspense, { fallback: null }, pnextClientBoundary(h, vnode));
+  const wrapped = ${facts.suspense !== false ? 'h(Suspense, { fallback: null }, pnextClientBoundary(h, vnode))' : 'pnextClientBoundary(h, vnode)'};
   if (source !== root) adoptPreserved(render, root, wrapped);
   else mount(hydrate, render, root, wrapped);
 }`
@@ -1248,27 +1267,23 @@ function wrapInBoundary(vnodeExpression: string, nextCompat?: boolean) {
 }
 
 // Emits the per-route boundary helper referenced by wrapInBoundary. The Suspense wrapper is
-// unconditional under compat - dropping it kills the tree. The error boundary inside it is emitted
-// only for an app that has an error.*/not-found.* for it to render: with none it would just re-throw,
-// and the deferred window last resort already owns that path.
-function clientBoundaryHelperSource(
-  nextCompat?: boolean,
-  boundary?: boolean,
-  builtinNotFound?: boolean,
-) {
+// unconditional under compat - dropping it kills the tree. The boundary COMPONENT arrives through
+// config (always set under compat, full tier or bare) rather than being imported here: this module is
+// shared app-wide, so naming the full boundary would put the whole cluster - and its built-in 404 UI -
+// on the first paint of every route in an app where any single route has an error file.
+function clientBoundaryHelperSource(nextCompat?: boolean, suspense?: boolean) {
   if (!nextCompat) return '';
-  const inner = boundary
-    ? `h(ClientErrorBoundary, {
+  // A suspense-free app (no lazy/use/async components anywhere in its client graph) keeps the error
+  // boundary but drops the Suspense wrapper - and preact/compat with it.
+  const boundary = `h(config.errorBoundary, {
       errorComponent: config.errorComponent,
-      notFoundComponent: config.notFoundComponent,${
-        builtinNotFound ? '\n      builtInNotFound: __PNextBuiltInNotFound,' : ''
-      }
-      onReset: softRefreshRoute,
-    }, vnode)`
-    : 'vnode';
+      notFoundComponent: config.notFoundComponent,
+      builtInNotFound: config.builtInNotFound,
+      onReset: config.onBoundaryReset,
+    }, vnode)`;
   return `
   function pnextBoundary(vnode) {
-    return h(Suspense, { fallback: null }, ${inner});
+    return ${suspense ? `h(Suspense, { fallback: null }, ${boundary})` : boundary};
   }
 `;
 }

package/src/compat/actions/action-client.ts

@@ -51,6 +51,13 @@ let warmDispatch: ((id: string, args: unknown[]) => Promise<unknown>) | undefine
 
 const loadDispatch = () => dispatchRuntime().then(module => (warmDispatch = module.callAction));
 
+// Warming is speculative: offline (or any failed chunk fetch) must not surface as an unhandled
+// rejection, which the client error last-resort escalates to the global-error document. A real
+// action call still awaits - and rejects through - loadDispatch.
+const warmDispatchChunk = () => {
+  void loadDispatch().catch(() => undefined);
+};
+
 function callAction(id: string, args: unknown[]): Promise<unknown> {
   return warmDispatch ? warmDispatch(id, args) : loadDispatch().then(call => call(id, args));
 }
@@ -522,7 +529,7 @@ export function installActionRuntime() {
     // Hydration is also where the dispatch chunk gets warmed (see loadDispatch):
     // past first paint, before any click, and `import()` dedups the repeats.
     window.addEventListener('pnext:hydrated', stripProgressiveActionIds);
-    window.addEventListener('pnext:hydrated', loadDispatch);
+    window.addEventListener('pnext:hydrated', warmDispatchChunk);
     stripProgressiveActionIds();
   }
   installVNodeHook();

package/src/compat/actions/action-dispatch.ts

@@ -555,7 +555,17 @@ async function refresh() {
 
 async function swapDocument(response: Response) {
   const html = await response.text();
-  await replaceDocument(html);
+  // Next renders an action's notFound() in place, so a robots meta the page
+  // itself declared survives it. Our swap rewrites the document: carry the live
+  // tag over, replacing the server's fallback noindex when one was injected.
+  const robots = document.querySelector('meta[name="robots"]')?.outerHTML;
+  const pattern = /<meta[^>]+name=["']robots["'][^>]*\/?>/i;
+  const withRobots = robots
+    ? pattern.test(html)
+      ? html.replace(pattern, robots)
+      : html.replace('</head>', `${robots}</head>`)
+    : html;
+  await replaceDocument(withRobots);
 }
 
 /**

package/src/compat/actions/discovery.ts

@@ -36,6 +36,13 @@ export interface ActionDiscovery {
   modules: DiscoveredActionModule[];
   /** Every source file that is a 'use server' module, for the client alias. */
   actionFiles: Set<string>;
+  /**
+   * First-party files that import a node_modules action module. The route-fact scan's client-entry-reason
+   * walk never descends into node_modules (see collectSourceFiles), so a route reaching an action only
+   * through one of these files needs its 'actions' reason added explicitly - the action file itself never
+   * lands in route.sourceFiles the way a first-party action module does.
+   */
+  actionImporters: Set<string>;
 }
 
 /**
@@ -51,7 +58,7 @@ export async function discoverActions(
   config: ResolvedConfig,
   options: { modulePathFor?: (file: string) => string } = {},
 ): Promise<ActionDiscovery> {
-  const empty: ActionDiscovery = { modules: [], actionFiles: new Set() };
+  const empty: ActionDiscovery = { modules: [], actionFiles: new Set(), actionImporters: new Set() };
   if (!nextCompatEnabled(config)) return empty;
 
   const roots = actionScanRoots(config);
@@ -70,7 +77,13 @@ export async function discoverActions(
     }
   }
   const sources = readSources(files);
-  for (const file of discoverNodeModuleActionFiles(config, files, sources, seen)) {
+  const { files: nodeModuleActionFiles, importers: actionImporters } = discoverNodeModuleActionFiles(
+    config,
+    files,
+    sources,
+    seen,
+  );
+  for (const file of nodeModuleActionFiles) {
     files.push(file);
     seen.add(file);
   }
@@ -100,7 +113,7 @@ export async function discoverActions(
     actionFiles.add(file);
   }
 
-  return { modules, actionFiles };
+  return { modules, actionFiles, actionImporters };
 }
 
 /**
@@ -159,8 +172,9 @@ function discoverNodeModuleActionFiles(
   sourceFiles: string[],
   sources: Map<string, string>,
   seen: Set<string>,
-) {
+): { files: string[]; importers: Set<string> } {
   const actionFiles = new Set<string>();
+  const importers = new Set<string>();
   // A bare specifier resolves purely from the importer's resolution root, so
   // both the resolution and the 'use server' verdict are cached app-wide, and
   // each is derived only for the specifiers a file actually reaches.
@@ -205,10 +219,13 @@ function discoverNodeModuleActionFiles(
     if (!reachable) continue;
     for (const specifier of importSpecifiers(source, file)) {
       const target = actionTarget(resolveRoot, file, specifier);
-      if (target) actionFiles.add(target);
+      if (target) {
+        actionFiles.add(target);
+        importers.add(file);
+      }
     }
   }
-  return [...actionFiles];
+  return { files: [...actionFiles], importers };
 }
 
 // Every string literal in an import position: `from 'x'`, `import 'x'`,

package/src/compat/bundler/optimize-package-imports.ts

@@ -14,7 +14,11 @@
 
 import path from 'node:path';
 import { readFileSync } from 'node:fs';
-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 { rewriteFacts, type ImportBinding } from '../../resolve/scan-facts';
 import { spliceSource } from '../../dev/module-transform';
 import { resolvePackageSpecifier, resolveVendorPackageSpecifier } from '../../resolve/imports';

package/src/compat/bundler/worker.ts

@@ -17,7 +17,8 @@ import { createHash } from 'node:crypto';
 import { existsSync, statSync } from 'node:fs';
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { build, type Plugin } from 'esbuild';
+import type { Plugin } from 'esbuild';
+import { build } from '../../utils/esbuild';
 import { publicEnvDefines, type ResolvedConfig } from '../../config';
 import { getAssetExtensions } from '../../extensions';
 

package/src/compat/client/errors/bare-boundary.ts

@@ -0,0 +1,32 @@
+// Bare tier of the client error boundary (see ./error-boundary): a route with no error.*/not-found.*
+// still needs one so hydration throws reach the window last resort (not preact's diff) and primitive
+// throws keep their raw value en route to global-error. Exactly those two behaviors, ~0.5 KB raw.
+import { Component, type ComponentChildren } from 'preact';
+import { normalizeBoundaryError } from './primitive-throw';
+
+interface BareBoundaryState {
+  error: unknown;
+  hasError: boolean;
+}
+
+export class BareErrorBoundary extends Component<{ children?: unknown }, BareBoundaryState> {
+  state: BareBoundaryState = { error: null, hasError: false };
+
+  static getDerivedStateFromError(error: unknown): BareBoundaryState {
+    return { error: normalizeBoundaryError(error), hasError: true };
+  }
+
+  render(): ComponentChildren {
+    if (!this.state.hasError) return this.props.children;
+    const { error } = this.state;
+    // A primitive would arrive at the window handler as a synthesized Error, so
+    // escalate it to global-error directly (deferred tier) with its raw value.
+    // Everything else re-throws: unmarked, so the window last resort still sees
+    // a genuinely uncaught error and drives it.
+    if (error === null || typeof error !== 'object') {
+      void import('./global-error').then(module => module.escalateToGlobalError(error));
+      return null;
+    }
+    throw error as Error;
+  }
+}

package/src/compat/client/errors/error-boundary.ts

@@ -19,7 +19,7 @@
 import { Component, h, type ComponentChildren, type ComponentType } from 'preact';
 import { isControlFlowError, handleControlFlowError } from './control-flow';
 import { isNotFoundError } from '../../../api/navigation';
-import { untagPrimitiveThrow } from './primitive-throw';
+import { normalizeBoundaryError } from './primitive-throw';
 
 // ---------------------------------------------------------------------------
 // KNOWN GAP (preact core, not fully fixable from an options hook): a CLIENT
@@ -72,20 +72,6 @@ export function toClientError(value: unknown): Error {
   return new Error(String(value));
 }
 
-function normalizeBoundaryError(error: unknown): unknown {
-  // Preact-core interop tag (see primitive-throw.ts): a `throw undefined`/`null`
-  // arrives here re-thrown as a tagged Error so it survived preact's own
-  // `e.then` suspense check without crashing. Unwrap back to the raw value.
-  const untagged = untagPrimitiveThrow(error);
-  if (untagged !== error) return untagged;
-  if (error instanceof Error) {
-    // Fallback for any crash that slips through un-tagged (defense in depth).
-    if (error.message === "Cannot read properties of undefined (reading 'then')") return undefined;
-    if (error.message === "Cannot read properties of null (reading 'then')") return null;
-  }
-  return error;
-}
-
 // A boundary that catches (or escalates) a real error marks it here so the
 // window-listener last resort (install.ts) knows the error was already handled
 // by the nearest-boundary path and must NOT also drive it to global-error.

package/src/compat/client/errors/primitive-throw.ts

@@ -34,6 +34,22 @@ export function untagPrimitiveThrow(error: unknown): unknown {
   return isTaggedPrimitiveThrow(error) ? error[RAW_VALUE] : error;
 }
 
+/**
+ * What a boundary hands its error UI: the raw value behind a tagged primitive
+ * throw, with a message-shaped fallback for a crash that slipped through untagged.
+ * Lives here rather than in a boundary so both boundary tiers share it without
+ * the bare one pulling in the full cluster.
+ */
+export function normalizeBoundaryError(error: unknown): unknown {
+  const untagged = untagPrimitiveThrow(error);
+  if (untagged !== error) return untagged;
+  if (error instanceof Error) {
+    if (error.message === "Cannot read properties of undefined (reading 'then')") return undefined;
+    if (error.message === "Cannot read properties of null (reading 'then')") return null;
+  }
+  return error;
+}
+
 /**
  * A value preact's diff.js catch block would crash on when narrowing for a suspending thenable
  * (`e.then`): null and undefined - the only two JS values where the property access itself throws.

package/src/compat/client/link-status.ts

@@ -1,7 +1,7 @@
 // Per-link navigation pending state for `useLinkStatus()` (next/link). A single link is "pending" at a
 // time: the last one whose click started an in-flight soft navigation. It clears on completion, and on
 // any navigation started elsewhere - all of which broadcast a location change.
-import { createContext } from 'preact/compat';
+import { createContext } from 'preact';
 import { softNavigate } from '../../api/router';
 import { locationListeners, onNavigationStart } from '../../api/router/events';
 import { patchHistory } from '../../api/client-navigation';

package/src/compat/css/lightningcss.ts

@@ -11,6 +11,7 @@
 
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { loadNative } from '../../utils/native-require';
 import { getNextConfig } from '../next/config-loader';
 
 interface LightningModule {
@@ -37,7 +38,7 @@ function loadLightningcss(root: string): LightningModule | null {
   let loaded: LightningModule | null = null;
   try {
     const require = createRequire(path.join(root, 'package.json'));
-    loaded = require('lightningcss') as LightningModule;
+    loaded = loadNative(() => require('lightningcss') as LightningModule);
   } catch {
     loaded = null;
   }

package/src/compat/css/modules.ts

@@ -116,12 +116,13 @@ function cssModuleMapping(file: string, root: string) {
 export function nextCssSource(file: string, root: string) {
   const resolved = path.resolve(file);
   const parts = resolved.split(path.sep);
+  // Matched on the cache segments alone: the out dir above them is configurable
+  // (distDir) and gains a `dev/` level under a dev server.
   const buildClientIndex = parts.findIndex(
-    (part, index) =>
-      part === '.pnext' && parts.slice(index + 1, index + 4).join('/') === 'cache/server/build-client',
+    (_, index) => parts.slice(index, index + 3).join('/') === 'cache/server/build-client',
   );
   if (buildClientIndex !== -1) {
-    const source = path.join(root, ...parts.slice(buildClientIndex + 4));
+    const source = path.join(root, ...parts.slice(buildClientIndex + 3));
     if (existsSync(source)) return source;
   }
   const generatedIndex = parts.lastIndexOf('pnext-pages-compat');

package/src/compat/lifecycle/instrumentation-client.ts

@@ -19,7 +19,7 @@
 
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
-import { build } from 'esbuild';
+import { build } from '../../utils/esbuild';
 import type { ResolvedConfig } from '../../config';
 import { getNextConfig } from '../next/config-loader';
 import { instrumentationLookupRoots } from './instrumentation';

package/src/compat/lifecycle/instrumentation.ts

@@ -16,7 +16,8 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } fr
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
-import { build, type Plugin } from 'esbuild';
+import type { Plugin } from 'esbuild';
+import { build } from '../../utils/esbuild';
 import type { ResolvedConfig } from '../../config';
 import { resolveExternalLoadTarget } from '../../resolve/imports';
 import { compatAliases, reactServerLayerAliases } from '../index';
@@ -136,7 +137,9 @@ async function importInstrumentation(
   suffix = '',
 ): Promise<InstrumentationModule> {
   const root = config.root;
-  const outDir = path.join(root, '.pnext', 'instrumentation');
+  // Under config.outPath, so a dev server's scratch bundle lives in its own
+  // subtree and a concurrent build never removes it mid-import.
+  const outDir = path.join(config.outPath, 'instrumentation');
   mkdirSync(outDir, { recursive: true });
   const outfile = path.join(outDir, `instrumentation.${Date.now()}${suffix}.mjs`);
   const tsconfig = path.join(root, 'tsconfig.json');

package/src/compat/next/config-loader.ts

@@ -17,7 +17,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { build } from 'esbuild';
+import { build } from '../../utils/esbuild';
 import { setConfig } from './config';
 import { setCacheComponents } from '../../ppr';
 import { PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_BUILD } from './constants';
@@ -131,10 +131,24 @@ function findTsconfig(root: string): string | undefined {
  * The emitted file is written next to the config so Node resolves the app's
  * node_modules and relative assets from the original location.
  */
-async function importConfigModule(configPath: string, root: string): Promise<NextConfigExport> {
-  const outDir = path.join(root, '.pnext', 'config');
-  mkdirSync(outDir, { recursive: true });
+async function importConfigModule(
+  configPath: string,
+  root: string,
+  dev: boolean,
+): Promise<NextConfigExport> {
   const cjs = cjsConfigFormat(configPath, root);
+  if (process.env.PNEXT_CONFIG_FAST !== '0' && selfContainedConfig(configPath)) {
+    // Nothing left for the bundle pass to do, and Bun loads every supported config format natively -
+    // so skip it. Worth a special case because this is the common shape and the pass is not cheap:
+    // it loads esbuild and spawns its service child on the dev/start boot critical path.
+    if (cjs) return createRequire(pathToFileURL(configPath))(configPath) as NextConfigExport;
+    const module = (await import(pathToFileURL(configPath).href)) as { default?: NextConfigExport };
+    return module.default ?? {};
+  }
+  // Dev keeps its scratch bundle in its own subtree; a concurrent build wipes
+  // only the build-owned `config/`.
+  const outDir = path.join(root, '.pnext', ...(dev ? ['dev'] : []), 'config');
+  mkdirSync(outDir, { recursive: true });
   // Content-addressed, not timestamped: a per-boot name leaked one bundle per
   // dev start and put a path that changes every boot into the module graph,
   // which renamed every artifact that could reach it.
@@ -193,6 +207,20 @@ async function importConfigModule(configPath: string, root: string): Promise<Nex
   }
 }
 
+/**
+ * Whether the config reaches nothing the bundle pass provides: `import`/`require` are its only routes
+ * to other modules and `__dirname`/`__filename` the only globals the pass defines. A false positive
+ * (token in a comment/string) just runs the bundle pass we would have run anyway.
+ */
+function selfContainedConfig(configPath: string): boolean {
+  try {
+    const source = readFileSync(configPath, 'utf8').replaceAll('import.meta', '');
+    return !/\b(?:import|require|__dirname|__filename)\b/.test(source);
+  } catch {
+    return false;
+  }
+}
+
 function cjsConfigFormat(configPath: string, root: string): boolean {
   if (configPath.endsWith('.cjs') || configPath.endsWith('.cts')) return true;
   if (!configPath.endsWith('.js')) return false;
@@ -538,7 +566,7 @@ export async function loadNextConfig(
   }
   let exported: NextConfigExport;
   try {
-    exported = await importConfigModule(configPath, root);
+    exported = await importConfigModule(configPath, root, Boolean(options.dev));
   } catch (error) {
     // A next.config that pulls in an optional wrapper dependency not installed
     // in this app (e.g. @next/mdx when deps are declared but not installed)

package/src/compat/next/dynamic.tsx

@@ -24,11 +24,15 @@ export default function dynamic<Props extends object = object>(
   const Lazy = lazy(() => loader().then(module => ({ default: componentFromModule(module) })));
   const DynamicComponent = ((props: Props) => {
     const Loading = options.loading;
-    const content = h(Suspense, { fallback: Loading ? h(Loading, props) : null }, h(Lazy, props));
-    return options.ssr === false
-      ? h('pnext-dynamic', { style: { display: 'contents' } },
-          (!process.browser && typeof window === 'undefined') ? null : content)
-      : content;
+    // ssr:false renders nothing on the server, so the client mount is a *hydration* whose only child
+    // suspends. preact/compat nulls a hydrating vnode's type when it unmounts, and Suspense reuses the
+    // same props.children vnode on its resolve re-render - the poisoned element then renders as text.
+    // The hooks-based core component loads without suspending, so that boundary is never entered.
+    if (options.ssr === false) {
+      return h('pnext-dynamic', { style: { display: 'contents' } },
+        (!process.browser && typeof window === 'undefined') ? null : h(coreDynamic, props));
+    }
+    return h(Suspense, { fallback: Loading ? h(Loading, props) : null }, h(Lazy, props));
   }) as DynamicWithReference<Props>;
 
   DynamicComponent[dynamicReferenceSymbol] = coreDynamic[dynamicReferenceSymbol];