@wular/pnext 0.0.1

package/src/client/profile.ts

@@ -0,0 +1,75 @@
+// Phase decomposition for the client stage (read / transform / react-compiler /
+// esbuild / write), off unless PNEXT_CLIENT_PROFILE is set. 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);
+
+const totals = new Map<string, number>();
+const spans = new Map<string, [number, number][]>();
+
+/** Total wall covered by at least one span (overlaps counted once). */
+function unionMs(intervals: [number, number][]) {
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
+  let total = 0;
+  let [openStart, openEnd] = sorted[0] ?? [0, 0];
+  for (const [start, end] of sorted.slice(1)) {
+    if (start > openEnd) {
+      total += openEnd - openStart;
+      [openStart, openEnd] = [start, end];
+    } else if (end > openEnd) {
+      openEnd = end;
+    }
+  }
+  return total + (openEnd - openStart);
+}
+
+export const clientProfile = {
+  enabled,
+  /** Time `task` under `phase`. Returns the task's value untouched. */
+  time<T>(phase: string, task: () => T): T {
+    if (!enabled) return task();
+    const start = performance.now();
+    try {
+      return task();
+    } finally {
+      totals.set(phase, (totals.get(phase) ?? 0) + (performance.now() - start));
+    }
+  },
+  /**
+   * Async phases overlap (esbuild runs onLoad concurrently), so summing each call's wall would count
+   * the same second many times. Record spans and report the union - the wall the phase occupies.
+   */
+  async timeAsync<T>(phase: string, task: () => Promise<T>): Promise<T> {
+    if (!enabled) return task();
+    const start = performance.now();
+    try {
+      return await task();
+    } finally {
+      (spans.get(phase) ?? spans.set(phase, []).get(phase)!).push([start, performance.now()]);
+    }
+  },
+  count(key: string, by = 1) {
+    if (!enabled) return;
+    totals.set(key, (totals.get(key) ?? 0) + by);
+  },
+  reset() {
+    totals.clear();
+    spans.clear();
+  },
+  snapshot(): Record<string, number> {
+    return {
+      ...Object.fromEntries(totals),
+      ...Object.fromEntries([...spans].map(([phase, list]) => [phase, unionMs(list)])),
+    };
+  },
+  /** Print the snapshot and clear it, so a second stage starts from zero. */
+  report(label: string) {
+    if (!enabled) return;
+    const snap = this.snapshot();
+    const line = Object.entries(snap)
+      .map(([phase, value]) => `${phase} ${value < 100 ? value.toFixed(1) : Math.round(value)}`)
+      .join(' · ');
+    console.log(`pnext client profile [${label}] ${line}`);
+    this.reset();
+  },
+};

package/src/client/react-compiler.ts

@@ -0,0 +1,94 @@
+import { transform, transformSync, type TransformOptions, type TransformResult } from 'oxc-transform';
+import type { getCompatModeExtensions } from '../extensions';
+
+type ReactCompilerOptions = NonNullable<
+  ReturnType<ReturnType<typeof getCompatModeExtensions>['reactCompilerOptions']>
+>;
+
+// oxc-transform runs the React Compiler (Rust port) plus TypeScript stripping
+// in a single pass, replacing the @babel/core round-trip. JSX is left intact
+// (`jsx: 'preserve'`) so esbuild stays the single source of truth for the
+// preact JSX transform downstream.
+function compilerOptions(options: ReactCompilerOptions): TransformOptions {
+  return {
+    jsx: 'preserve',
+    sourcemap: false,
+    reactCompiler: {
+      panicThreshold: 'critical_errors',
+      target: options.target as '17' | '18' | '19',
+    },
+  };
+}
+
+/**
+ * The React Compiler pass. It has no esbuild plugin of its own: the client-source loader owns every
+ * first-party source file and calls this as the last step of that file's single rewrite pass, so
+ * the compiler applies exactly once regardless of plugin registration order. oxc strips TS types as
+ * part of the pass, so no separate type-import cleanup is needed.
+ *
+ * `transform`, not `transformSync`: the async binding runs on oxc's Rust threadpool, so esbuild's
+ * concurrent onLoad callbacks compile the whole route set in parallel instead of queueing on the
+ * JS thread.
+ */
+export async function transformReactCompiler(
+  source: string,
+  file: string,
+  options: ReactCompilerOptions,
+) {
+  return reactCompilerResult(await transform(file, source, compilerOptions(options)), source, file);
+}
+
+/** Same pass, for the few callers that cannot await (kept in lock-step above). */
+export function transformReactCompilerSync(
+  source: string,
+  file: string,
+  options: ReactCompilerOptions,
+) {
+  return reactCompilerResult(transformSync(file, source, compilerOptions(options)), source, file);
+}
+
+function reactCompilerResult(result: TransformResult, source: string, file: string) {
+  // When the compiler cannot compile a function (rule-of-React violation, unsupported library, a
+  // construct the Rust port does not yet handle) it reports a diagnostic. If the whole file trips one,
+  // oxc emits no code at all - unlike Babel, which skips just that function - so fall back to the
+  // untransformed source and let esbuild strip types and handle JSX; the file ships un-memoized.
+  // `panicThreshold` does not change this: every value still yields empty output on a hard bailout.
+  if (!result.code) {
+    // Only genuine transform failures (not React Compiler bailouts) are worth
+    // surfacing; esbuild re-parses the fallback source and would flag the rest.
+    const failures = result.errors.filter(error => !error.message.startsWith('[ReactCompiler]'));
+    if (failures.length > 0) {
+      console.error(
+        `React Compiler (oxc) failed for ${file}:\n${failures.map(error => error.message).join('\n')}`,
+      );
+    }
+    return source;
+  }
+
+  return result.code;
+}
+
+export function stripPureTypeImports(source: string) {
+  return source
+    .replace(/^\s*import\s+type\s+[\s\S]*?\s+from\s+['"][^'"]+['"]\s*;?\s*$/gm, '')
+    .replace(
+      /^\s*import\s+\{([^}]*)\}\s+from\s+(['"][^'"]+['"])\s*;?\s*$/gm,
+      (_match, clause: string, specifier: string) => {
+        const valueSpecifiers = clause
+          .split(',')
+          .map(item => item.trim())
+          .filter(Boolean)
+          .filter(item => !item.startsWith('type '));
+
+        return valueSpecifiers.length > 0
+          ? `import { ${valueSpecifiers.join(', ')} } from ${specifier};`
+          : '';
+      },
+    );
+}
+
+/** JSX always; a plain .ts/.js only when it looks like it holds a component. */
+export function shouldReactCompile(source: string, file: string) {
+  if (/\.[cm]?[jt]sx$/.test(file)) return true;
+  return /\b(?:use[A-Z][\w$]*|createElement|memo|forwardRef)\b/.test(source);
+}

package/src/client/reference-stub.ts

@@ -0,0 +1,145 @@
+/**
+ * The stub a server-graph module gets in place of a `'use client'` file: a component object tagged
+ * with the reference the renderer matches islands by. Shared by the two places that cross a client
+ * boundary from the server graph - the dev module pass and the vendor bundler (a package's own
+ * `'use client'` files, reached mid-bundle).
+ */
+import path from 'node:path';
+import { clientReferenceId } from './reference';
+import { pathToFileHref } from '../config';
+import type { ResolvedConfig } from '../config';
+import { resolveImport } from '../resolve/imports';
+import { moduleExportNames, moduleExportStars } from '../resolve/scan-facts';
+import { readText } from '../utils/fs';
+
+export const clientReferenceRuntimeFile = path.resolve(import.meta.dirname, 'reference.ts');
+
+export interface ClientReferenceModuleOptions {
+  /**
+   * Inline `Symbol.for('pnext.clientReference')` instead of importing the
+   * runtime module. A stub esbuild BUNDLES (the vendor pass) has no way to
+   * reach pnext's own source tree, and the symbol is registry-global, so an
+   * inlined lookup is the same symbol the renderer tests for.
+   */
+  inlineSymbol?: boolean;
+}
+
+export function clientReferenceModuleSource(
+  sourceFile: string,
+  exportNames: string[],
+  options: ClientReferenceModuleOptions = {},
+) {
+  const reference = (exportName: string) =>
+    `createReference({ id: ${JSON.stringify(`c-${clientReferenceId(sourceFile, exportName)}`)}, file: ${JSON.stringify(sourceFile)}, exportName: ${JSON.stringify(exportName)} })`;
+  const defaultExport = exportNames.includes('default')
+    ? `export default ${reference('default')};`
+    : '';
+  const namedExports = exportNames
+    .filter(name => name !== 'default')
+    .map(name => `export const ${name} = ${reference(name)};`);
+  const symbol = options.inlineSymbol
+    ? `const clientReferenceSymbol = Symbol.for('pnext.clientReference');`
+    : `import { clientReferenceSymbol } from ${JSON.stringify(pathToFileHref(clientReferenceRuntimeFile))};`;
+
+  return `${symbol}
+
+function createReference(reference) {
+  function ClientReference({ children }) {
+    return children ?? null;
+  }
+  ClientReference[clientReferenceSymbol] = reference;
+  return ClientReference;
+}
+
+${defaultExport}
+${namedExports.join('\n')}
+`;
+}
+
+/**
+ * The names a stub must republish. `export *` is followed because the star's
+ * targets live in other files, and a name the stub omits is a hard link error
+ * at the importer.
+ */
+export async function clientReferenceExportNames(
+  config: ResolvedConfig,
+  file: string,
+  source?: string,
+  visited = new Set<string>(),
+): Promise<string[]> {
+  const key = path.resolve(file);
+  if (visited.has(key)) return [];
+  visited.add(key);
+  const text = source ?? (await readText(file));
+  const names = new Set(moduleExportNames(text, file));
+  // A CommonJS-style client module (`exports.X = ...`) has no ESM exports for
+  // the transpiler scan; recover the statically visible names so its reference
+  // shim exposes them (mirrors the client bundle's CJS-name recovery).
+  if (names.size === 0) {
+    for (const match of text.matchAll(/\bexports\.([A-Za-z_$][\w$]*)\s*=/g)) {
+      if (match[1] !== '__esModule') names.add(match[1]!);
+    }
+    if (/\bmodule\.exports\s*=/.test(text)) names.add('default');
+  }
+  // `export * from './x'` re-exports every named export of the target, whose
+  // names live in that module — union them recursively (default stays
+  // excluded, per ES module star semantics). `export * as ns from` exports
+  // only `ns`, which the own-module scan already lists.
+  for (const specifier of moduleExportStars(text, file)) {
+    const resolved = resolveImport(config.root, file, specifier);
+    if (!resolved || !isInside(config.workspaceRoot, resolved)) continue;
+    for (const name of await clientReferenceExportNames(config, resolved, undefined, visited)) {
+      if (name !== 'default') names.add(name);
+    }
+  }
+  return [...names];
+}
+
+/**
+ * Comments and preceding directives do not end the directive prologue. Hand-scanned rather than
+ * matched by a regex on purpose: the prologue grammar (a lazy repeat over an alternation whose
+ * branches both end in `*?`) is catastrophically ambiguous, so on a file with no directive but a
+ * few leading comments a backtracking engine tries every way of splitting the prefix. This scan is
+ * linear and allocation-free.
+ */
+export function hasUseClientDirective(source: string) {
+  const isSpace = (index: number) => {
+    const code = source.charCodeAt(index);
+    return code === 32 || (code >= 9 && code <= 13) || (code > 127 && /\s/.test(source[index]!));
+  };
+  let i = 0;
+  for (;;) {
+    while (i < source.length && isSpace(i)) i += 1;
+    if (source.startsWith('//', i)) {
+      const newline = source.indexOf('\n', i);
+      if (newline === -1) return false;
+      i = newline + 1;
+      continue;
+    }
+    if (source.startsWith('/*', i)) {
+      const end = source.indexOf('*/', i + 2);
+      if (end === -1) return false;
+      i = end + 2;
+      continue;
+    }
+    // Anything that is not a string literal ends the prologue.
+    const quote = source[i];
+    if (quote !== '"' && quote !== "'") return false;
+    let end = i + 1;
+    while (end < source.length) {
+      const char = source[end]!;
+      if (char === quote || char === '\n' || char === '\\') break;
+      end += 1;
+    }
+    if (source[end] !== quote) return false;
+    if (source.slice(i + 1, end) === 'use client') return true;
+    i = end + 1;
+    while (i < source.length && isSpace(i)) i += 1;
+    if (source[i] === ';') i += 1;
+  }
+}
+
+function isInside(root: string, file: string) {
+  const relative = path.relative(root, file);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}

package/src/client/reference.ts

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+
+export interface ClientReference {
+  id: string;
+  file: string;
+  exportName: string;
+  dynamic?: ClientDynamicReference;
+  cssImports?: string[];
+  /**
+   * A `'use client'` module imported only for its side effects (a bare
+   * `import './client-only'` with no bindings). It is never rendered as a
+   * component, but webpack eagerly initializes every client reference module in
+   * a route's bundle once any of them renders, so pnext bundles it into the
+   * client entry (a bare side-effect import) to run its top-level code. It has
+   * no SSR component, so it is excluded from every server-side marking pass.
+   */
+  sideEffect?: boolean;
+}
+
+export interface ClientDynamicReference {
+  load?: 'render' | 'visible';
+  rootMargin?: string;
+  ssr?: boolean;
+  threshold?: number | number[];
+}
+
+export const clientReferenceSymbol = Symbol.for('pnext.clientReference');
+
+export type ClientComponent = ((props: Record<string, unknown>) => unknown) & {
+  [clientReferenceSymbol]?: ClientReference;
+};
+
+export function clientReferenceId(file: string, exportName: string) {
+  return createHash('sha256')
+    .update(file)
+    .update('\0')
+    .update(exportName)
+    .digest('hex')
+    .slice(0, 10);
+}
+
+export function ssrClientReference(reference: Pick<ClientReference, 'dynamic' | 'sideEffect'>) {
+  if (reference.sideEffect) return false;
+  if (reference.dynamic?.ssr === false) return false;
+  if (reference.dynamic?.load === 'visible' && reference.dynamic.ssr !== true) return false;
+  return true;
+}