@wular/pnext 0.0.1 → 0.0.3

package/src/client/build.ts

@@ -38,6 +38,7 @@ import {
   clientRuntimeSource,
   type ClientRuntimeFacts,
 } from './entry';
+import { clientSuspenseFree } from './compat-surface';
 import {
   ensurePrebuiltRuntime,
   prebuiltAssets,
@@ -142,14 +143,14 @@ function appUsesActions(routes: RouteManifestEntry[], hasServerActions?: boolean
 }
 
 /**
- * Whether this route has an `error.*` or `not-found.*` for the in-tree ClientErrorBoundary to
- * render. Without one the boundary would only re-throw, and the deferred window last resort already
- * owns that path - so the whole boundary cluster stays off first paint.
+ * Per-route half of the same question: the scan stamps `actions`/`form` reasons on every page whose
+ * closure can dispatch one, so a route carrying neither ships no action runtime even in an app with
+ * actions elsewhere.
  */
-function hasRouteErrorBoundary(config: ResolvedConfig, route: RouteManifestEntry): boolean {
+function routeUsesActions(route: RouteManifestEntry, appActions: boolean) {
+  if (!appActions) return false;
   return (
-    Boolean(routeErrorFile(config, route) ?? routeNotFoundFile(config, route)) ||
-    routeThrowsClientControlFlow(route)
+    route.clientEntryReasons?.some(reason => reason === 'actions' || reason === 'form') === true
   );
 }
 
@@ -301,11 +302,10 @@ function surfaceSignature(config: ResolvedConfig, route: RouteManifestEntry, act
       {
         route,
         shell: hasClientRootLayout(config, route),
-        boundary: hasRouteErrorBoundary(config, route),
-        notFound: Boolean(routeNotFoundFile(config, route)),
       },
     ],
     nextCompat,
+    !routeSuspenseFree(config, route),
   );
   return JSON.stringify([
     nextCompat,
@@ -337,6 +337,7 @@ async function preparePrebuilt(
   dev: boolean,
   sourceOf: (importer: string) => string | undefined,
   signature = '',
+  reactLite = false,
 ): Promise<PreparedPrebuilt | undefined> {
   if (!prebuiltEnabled()) return undefined;
   const buildOptions = baseClientBuildOptions(config, dev);
@@ -353,7 +354,7 @@ async function preparePrebuilt(
     publicPath,
     assetPath,
     buildOptions,
-    plugins: () => clientBuildPlugins(config, createClientSourcePipeline(config)),
+    plugins: () => clientBuildPlugins(config, createClientSourcePipeline(config), [], reactLite),
   };
   const runtime = await ensurePrebuiltRuntime(options);
   const unprobed = new Set<string>();
@@ -417,11 +418,13 @@ function deferredDynamicExternalPlugin(): Plugin {
 export async function buildClientEntry({ config, route, outDir, dev }: ClientBuildOptions) {
   conventionCache.clear();
   await ensureDir(outDir);
+  const suspense = routeSuspenseFree(config, route) === false;
   const source = clientEntrySource({
     deferredDynamicHref: devDeferredDynamicHref(dev),
     pageFile: route.client ? route.file : undefined,
     clientReferences: route.clientReferences,
     nextCompat: nextCompatEnabled(config),
+    suspense,
     // Single-route (dev / batch fallback) build: no app-wide action manifest here.
     actions: true,
     errorFile: routeErrorFile(config, route),
@@ -441,11 +444,10 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
       {
         route,
         shell: hasClientRootLayout(config, route),
-        boundary: hasRouteErrorBoundary(config, route),
-        notFound: Boolean(routeNotFoundFile(config, route)),
       },
     ],
     nextCompatEnabled(config),
+    suspense,
   );
   const prebuilt = await clientProfile.timeAsync('prebuilt', () => preparePrebuilt(
     config,
@@ -458,6 +460,7 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
     // One route is its own surface group, so the key is the same one the batch
     // build would give this route's group — dev and prod derive it identically.
     surfaceSignature(config, route, true),
+    !suspense,
   ));
 
   let metafile: Metafile | undefined;
@@ -478,7 +481,7 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
           ...(prebuilt ? [prebuilt.plugin] : []),
           ...(devDeferredDynamicHref(dev) ? [deferredDynamicExternalPlugin()] : []),
           clientRuntimePlugin(runtimeFacts),
-        ]),
+        ], !suspense),
       })),
     );
     metafile = result.metafile;
@@ -611,7 +614,8 @@ export async function buildClientEntries({
         pageFile: route.client ? route.file : undefined,
         clientReferences: route.clientReferences,
         nextCompat: nextCompatEnabled(config),
-        actions,
+        suspense: !routeSuspenseFree(config, route),
+        actions: routeUsesActions(route, actions),
         errorFile: routeErrorFile(config, route),
         globalErrorFile: globalErrorFile(config),
         notFoundFile: routeNotFoundFile(config, route),
@@ -697,17 +701,16 @@ function surfaceGroups(
       members.map(entry => ({
         route: entry.route,
         shell: hasClientRootLayout(config, entry.route),
-        boundary: hasRouteErrorBoundary(config, entry.route),
-        notFound: Boolean(routeNotFoundFile(config, entry.route)),
       })),
       nextCompatEnabled(config),
+      !members.every(entry => routeSuspenseFree(config, entry.route)),
     );
   // eslint-disable-next-line turbo/no-undeclared-env-vars
   if (!prebuiltEnabled() || process.env.PNEXT_PREBUILT_GROUPS === '0')
     return [{ signature: '', facts: facts(entries), entries }];
   const bySignature = new Map<string, ClientEntry[]>();
   for (const entry of entries) {
-    const signature = surfaceSignature(config, entry.route, actions);
+    const signature = surfaceSignature(config, entry.route, routeUsesActions(entry.route, actions));
     const members = bySignature.get(signature) ?? [];
     bySignature.set(signature, members);
     members.push(entry);
@@ -738,6 +741,7 @@ async function buildEntryGroup({
   pipeline: ClientSourcePipeline;
   verbose?: boolean;
 }): Promise<BuiltEntryGroup> {
+  const reactLite = group.facts.suspense === false;
   const prebuilt = await clientProfile.timeAsync('prebuilt', () =>
     preparePrebuilt(
       config,
@@ -749,6 +753,7 @@ async function buildEntryGroup({
         return entry?.source ?? pipeline.sourceOf(importer) ?? readTextSyncSafe(importer);
       },
       group.signature,
+      reactLite,
     ),
   );
 
@@ -766,7 +771,7 @@ async function buildEntryGroup({
         ...(prebuilt ? [prebuilt.plugin] : []),
         virtualEntryPlugin(group.entries),
         clientRuntimePlugin(group.facts),
-      ]),
+      ], reactLite),
     }));
     metafile = result.metafile;
   } catch (error) {
@@ -791,6 +796,30 @@ async function buildEntryGroup({
  * page's own file. Deliberately NOT a module walk: this set is free (the scan produced it), it is
  * the bulk of any app's first-party client graph, and whatever it misses esbuild still discovers.
  */
+/**
+ * Whether this route's client graph provably never suspends (see clientSuspenseFree): its entry
+ * then drops the Suspense island wrapper and its `react` alias points at the compat-free lite shim.
+ * Memoized per build; a group of routes qualifies iff every member does.
+ */
+function routeSuspenseFree(config: ResolvedConfig, route: RouteManifestEntry): boolean {
+  if (!nextCompatEnabled(config)) return false;
+  return memoConvention(`suspenseFree:${route.id}`, () => {
+    const seeds: string[] = [];
+    if (route.client) seeds.push(route.file);
+    for (const reference of route.clientReferences) seeds.push(reference.file);
+    for (const file of [
+      routeErrorFile(config, route),
+      globalErrorFile(config),
+      routeNotFoundFile(config, route),
+      // Shell layouts hydrate client-side only when the root layout is 'use client'.
+      ...(hasClientRootLayout(config, route) ? shellLayoutOrder(config, route) : []),
+    ]) {
+      if (file) seeds.push(file);
+    }
+    return clientSuspenseFree(seeds);
+  });
+}
+
 function routeClientSources(routes: RouteManifestEntry[]) {
   const files = new Set<string>();
   for (const route of routes) {
@@ -1141,6 +1170,7 @@ function clientBuildPlugins(
   config: ResolvedConfig,
   pipeline: ClientSourcePipeline,
   extra: Plugin[] = [],
+  reactLite = false,
 ): Plugin[] {
   return coalesceResolveHooks(instrumentedPlugins([
     serverOnlyClientImportPlugin(),
@@ -1153,13 +1183,18 @@ function clientBuildPlugins(
     linkedPackageClientResolvePlugin(config),
     clientStaticAssetPlugin(config),
     pipeline.plugin(),
-    importAliasPlugin(config),
+    importAliasPlugin(config, reactLite),
     cssModuleClientPlugin(),
   ]), 'pnext-client-resolve-chain');
 }
 
-function importAliasPlugin(config: ResolvedConfig): Plugin {
-  const aliases = getImportAliasExtensions().aliases(config, 'client');
+function importAliasPlugin(config: ResolvedConfig, reactLite = false): Plugin {
+  const aliases = { ...getImportAliasExtensions().aliases(config, 'client') };
+  // Suspense-free tier: the app's `react` imports resolve to the compat-free lite shim, so the
+  // bundle ships preact core + hooks without preact/compat (see clientSuspenseFree).
+  if (reactLite && aliases.react) {
+    aliases.react = path.resolve(import.meta.dirname, '..', 'compat', 'react', 'client-lite.ts');
+  }
   const specifiers = Object.keys(aliases);
   return {
     name: 'pnext-import-alias',
@@ -2031,6 +2066,10 @@ 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) {
+    await writeText(path.join(outDir, 'metafile.json'), JSON.stringify(metafile));
+  }
   const chunksDir = path.join(outDir, 'chunks');
   const files = (await listFiles(chunksDir)).filter(file => file.endsWith('.js'));
   const labels = metafile ? chunkLabelsFromMetafile(metafile) : new Map<string, string>();

package/src/client/chunk-fold.ts

@@ -216,6 +216,42 @@ function availabilityAt(
   return answer;
 }
 
+/**
+ * A dynamic chunk only runs on a page that already ran a route entry, so the intersection over every
+ * entry that can reach it is a guaranteed availability floor - `inherited` intersects over direct
+ * importers whose own availability is still an estimate, and lands pessimistic behind route chunks.
+ */
+function entryFloors(metafile: Metafile, entries: string[], closures: Map<string, Set<string>>) {
+  const dynamicEdges = new Map<string, string[]>();
+  for (const [file, output] of Object.entries(metafile.outputs)) {
+    for (const imported of output.imports ?? []) {
+      if (imported.kind !== 'dynamic-import') continue;
+      (dynamicEdges.get(file) ?? dynamicEdges.set(file, []).get(file)!).push(imported.path);
+    }
+  }
+  const floors = new Map<string, Set<string>>();
+  for (const entry of entries) {
+    const own = closures.get(entry)!;
+    const seen = new Set(own);
+    const queue = [...own];
+    // `queue` grows inside the loop: every chunk this entry can reach by any
+    // chain of static and dynamic imports.
+    for (const current of queue) {
+      for (const target of dynamicEdges.get(current) ?? []) {
+        if (seen.has(target)) continue;
+        for (const file of closures.get(target) ?? staticClosure(metafile, target)) {
+          if (seen.has(file)) continue;
+          seen.add(file);
+          queue.push(file);
+        }
+        const floor = floors.get(target);
+        floors.set(target, floor ? intersect(floor, own) : new Set(own));
+      }
+    }
+  }
+  return floors;
+}
+
 /** Per load root, the chunks guaranteed to be on the page once it runs. */
 function availability(metafile: Metafile, entries: string[], dynamicTargets: Set<string>) {
   const available = new Map<string, Set<string>>();
@@ -224,6 +260,10 @@ function availability(metafile: Metafile, entries: string[], dynamicTargets: Set
     closures.set(root, staticClosure(metafile, root));
     available.set(root, new Set(closures.get(root)));
   }
+  for (const [target, floor] of entryFloors(metafile, entries, closures)) {
+    const set = available.get(target);
+    if (set) for (const file of floor) set.add(file);
+  }
   const importersOf = new Map<string, string[]>();
   for (const [file, output] of Object.entries(metafile.outputs)) {
     for (const imported of output.imports ?? []) {

package/src/client/compat-surface.ts

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Conservative static scan of a compat app's client graph deciding whether the client bundle can ship
+ * the lite react tier (preact core + hooks, no preact/compat, no Suspense island wrapper). Walks the
+ * seed files' relative-import closure; ANY signal it cannot prove safe - an unresolvable import, a bare
+ * package, a non-lite react name, a compat-only DOM prop, an async component shape - keeps the full
+ * tier. False negatives cost bytes, never correctness.
+ */
+
+/** react named imports the lite client shim (compat/react/client-lite.ts) serves. */
+const LITE_REACT_NAMES = new Set([
+  'Component',
+  'Fragment',
+  'StrictMode',
+  'cache',
+  'cacheSignal',
+  'cloneElement',
+  'createContext',
+  'createElement',
+  'createRef',
+  'isValidElement',
+  'startTransition',
+  'useActionState',
+  'useCallback',
+  'useContext',
+  'useDebugValue',
+  'useDeferredValue',
+  'useEffect',
+  'useId',
+  'useImperativeHandle',
+  'useInsertionEffect',
+  'useLayoutEffect',
+  'useMemo',
+  'useOptimistic',
+  'useReducer',
+  'useRef',
+  'useState',
+  'useTransition',
+  'version',
+  'ViewTransition',
+  'addTransitionType',
+]);
+
+// Framework client modules known not to pull preact/compat. Every other bare specifier (npm packages,
+// next/dynamic, next/image, ...) disqualifies the lite tier.
+const SAFE_BARE_SPECIFIERS = new Set([
+  'next/link',
+  'next/navigation',
+  'preact',
+  'preact/hooks',
+  'preact/jsx-runtime',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+]);
+
+// Compat-only semantics preact core lacks: React's onChange/onDoubleClick synthetic mapping,
+// default* form props, string refs, legacy class lifecycles - plus async component shapes (they
+// suspend). Matching anywhere in a file (even a comment) just falls back to the full tier.
+const UNSAFE_TOKENS =
+  /\bonChange\b|\bonDoubleClick\b|\bdefaultProps\b|\bgetSnapshotBeforeUpdate\b|\bcomponentWillReceiveProps\b|\bUNSAFE_\w+|\bref\s*=\s*["']|async\s+function\s+[A-Z]|(?:const|let|var)\s+[A-Z][\w$]*\s*=\s*async\b|export\s+default\s+async\b/;
+
+// defaultValue/defaultChecked are native DOM properties preact core assigns correctly on
+// input/textarea; only <select defaultValue> needs preact/compat's special handling.
+function unsafeDefaultValue(source: string) {
+  return source.includes('defaultValue') && source.includes('<select');
+}
+
+const STATIC_IMPORT = /(?:^|\n)\s*(?:import|export)\s+([^;'"]*?)\s*from\s*(['"])([^'"]+)\2/g;
+const BARE_IMPORT = /(?:^|\n)\s*import\s*(['"])([^'"]+)\1/g;
+const DYNAMIC_IMPORT = /\bimport\(\s*(['"])([^'"]+)\1/g;
+
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const SOURCE_EXTENSION = /\.(?:ts|tsx|js|jsx|mjs|cjs)$/;
+
+export function clientSuspenseFree(seeds: Iterable<string>): boolean {
+  const queue: string[] = [];
+  const visited = new Set<string>();
+  for (const seed of seeds) {
+    if (!seed || visited.has(seed)) continue;
+    visited.add(seed);
+    queue.push(seed);
+  }
+  while (queue.length > 0) {
+    const file = queue.pop()!;
+    if (!SOURCE_EXTENSION.test(file) || !existsSync(file)) return false;
+    let source: string;
+    try {
+      source = readFileSync(file, 'utf8');
+    } catch {
+      return false;
+    }
+    if (UNSAFE_TOKENS.test(source) || unsafeDefaultValue(source)) return false;
+    for (const [clause, specifier] of importsOf(source)) {
+      if (specifier === 'react') {
+        if (!liteReactClause(clause)) return false;
+        continue;
+      }
+      if (SAFE_BARE_SPECIFIERS.has(specifier)) continue;
+      if (specifier.startsWith('.')) {
+        if (clause !== undefined && typeOnlyClause(clause)) continue;
+        const resolved = resolveRelative(path.dirname(file), specifier);
+        if (resolved === ASSET) continue;
+        if (!resolved) return false;
+        if (!visited.has(resolved)) {
+          visited.add(resolved);
+          queue.push(resolved);
+        }
+        continue;
+      }
+      // Unknown bare package or framework module that may pull preact/compat.
+      if (clause === undefined || !typeOnlyClause(clause)) return false;
+    }
+  }
+  return true;
+}
+
+function* importsOf(source: string): Generator<[clause: string | undefined, specifier: string]> {
+  for (const match of source.matchAll(STATIC_IMPORT)) yield [match[1], match[3] ?? ''];
+  for (const match of source.matchAll(BARE_IMPORT)) yield [undefined, match[2] ?? ''];
+  for (const match of source.matchAll(DYNAMIC_IMPORT)) yield [undefined, match[2] ?? ''];
+}
+
+function typeOnlyClause(clause: string) {
+  return /^type\s/.test(clause.trim());
+}
+
+function liteReactClause(clause: string | undefined): boolean {
+  if (clause === undefined) return true;
+  const trimmed = clause.trim();
+  if (typeOnlyClause(trimmed)) return true;
+  // Default or namespace import: the whole surface is reachable - full tier.
+  const braceStart = trimmed.indexOf('{');
+  if (braceStart !== 0) return false;
+  const braceEnd = trimmed.indexOf('}');
+  if (braceEnd === -1) return false;
+  for (const entry of trimmed.slice(braceStart + 1, braceEnd).split(',')) {
+    const name = entry.trim();
+    if (!name || name.startsWith('type ')) continue;
+    const imported = (name.split(/\s+as\s+/)[0] ?? '').trim();
+    if (!LITE_REACT_NAMES.has(imported)) return false;
+  }
+  return true;
+}
+
+const ASSET = Symbol('pnext.compat-surface.asset');
+
+function resolveRelative(dir: string, specifier: string): string | typeof ASSET | undefined {
+  let base = path.resolve(dir, specifier);
+  const direct = fileAt(base);
+  if (direct) return direct;
+  // NodeNext-style `./x.js` pointing at `./x.ts(x)`.
+  if (/\.(?:js|jsx|mjs|cjs)$/.test(base)) base = base.replace(/\.[^.]+$/, '');
+  for (const extension of SOURCE_EXTENSIONS) {
+    const candidate = fileAt(base + extension);
+    if (candidate) return candidate;
+  }
+  for (const extension of SOURCE_EXTENSIONS) {
+    const candidate = fileAt(path.join(base, `index${extension}`));
+    if (candidate) return candidate;
+  }
+  return undefined;
+}
+
+function fileAt(candidate: string): string | typeof ASSET | undefined {
+  if (!existsSync(candidate)) return undefined;
+  try {
+    if (!statSync(candidate).isFile()) return undefined;
+  } catch {
+    return undefined;
+  }
+  // Styles/assets never carry react surface.
+  return SOURCE_EXTENSION.test(candidate) ? candidate : ASSET;
+}