@thomas.f/prnext 0.1.17-alpha → 0.1.18-alpha

package/build/react-compiler-report.mjs

@@ -0,0 +1,225 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { mkdir, open, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const reports = new AsyncLocalStorage(), graphs = new AsyncLocalStorage();
+const FILE_LIMIT = 1024, FUNCTION_LIMIT = 4096, EVENT_LIMIT = 16, TOTAL_EVENT_LIMIT = 8192;
+const GRAPH_INPUT_LIMIT = 4096;
+const REPORT_LIMIT = 8 * 1024 * 1024;
+export const REACT_COMPILER_REPORT_FILE = 'react-compiler-report.json';
+const statuses = new Set(['optimized', 'skipped', 'error', 'diagnostic', 'mixed']);
+const kinds = new Set(['CompileSuccess', 'CompileSkip', 'CompileError', 'CompileDiagnostic', 'PipelineError']);
+const slash = value => value.split(path.sep).join('/');
+const position = value => value && Number.isSafeInteger(value.line) && value.line > 0 && Number.isSafeInteger(value.column) && value.column >= 0
+  ? { line: value.line, column: value.column } : null;
+function text(value, root = '') {
+  if (typeof value !== 'string') return null;
+  return value.replaceAll(root || '\0', '<project>').replace(/https?:\/\/\S+/g, '')
+    .replace(/(?:file:\/\/\/)?[A-Za-z]:[\\/][^\s'")]+/g, '<path>')
+    .replace(/(?:^|\s)\/(?:[^\s/'"]+\/)+[^\s'")]+/g, ' <path>')
+    .replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 384) || null;
+}
+function relativeFile(root, file) {
+  if (typeof root !== 'string' || typeof file !== 'string') return null;
+  const relative = path.relative(root, file);
+  return !relative || relative.length > 1024 || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative) ? null : slash(relative);
+}
+
+/** Each build owns its collector. Failed/overlapping rebuilds cannot replace it. */
+export const withReactCompilerReporting = run => reports.run({ files: new Map(), graphs: new Map(), functionCount: 0, eventCount: 0, truncated: false }, run);
+export function configureReactCompilerReporting({ root, config, buildId, dev, compilerVersion }) {
+  const state = reports.getStore();
+  if (state) Object.assign(state, { root: path.resolve(root), enabled: !!config?.reactCompiler,
+    options: config?.reactCompiler || null, buildId, dev: !!dev, compilerVersion });
+}
+export const withReactCompilerGraph = (target, run) => graphs.run(target, run);
+
+/** Capture a narrow, source-free subset of the pinned compiler's public events. */
+export function compilerEvent(event, functions, { moduleOptOut = false, root = '' } = {}) {
+  if (!event || !kinds.has(event.kind)) return null;
+  const start = position(event.fnLoc?.start), end = position(event.fnLoc?.end);
+  const contains = fn => start && fn.start && fn.end && (fn.start.line < start.line || fn.start.line === start.line && fn.start.column <= start.column)
+    && (fn.end.line > start.line || fn.end.line === start.line && fn.end.column >= start.column);
+  const fn = functions.filter(contains).sort((a, b) => b.start.line - a.start.line || b.start.column - a.start.column)[0];
+  const detail = event.detail?.options || event.detail;
+  let status = event.kind === 'CompileSuccess' ? 'optimized' : event.kind === 'CompileSkip' ? 'skipped'
+    : event.kind === 'CompileDiagnostic' ? 'diagnostic' : 'error';
+  let reason = event.kind === 'PipelineError' ? 'React Compiler could not complete this function.' : text(event.reason ?? detail?.reason, root);
+  let category = text(detail?.category, root), policy = false;
+  // Compiler 1.0.0 emits CompileSuccess even when its module opt-out prevents
+  // emitting the compiled function. Success is not proof of emitted memoization.
+  if (moduleOptOut && event.kind === 'CompileSuccess') {
+    status = 'skipped'; reason = `Module uses "${moduleOptOut === true ? 'use no memo' : moduleOptOut}".`; category = 'Directive'; policy = true;
+  } else if (event.kind === 'CompileSkip' && fn?.optOut) {
+    reason = `Function uses "${fn.optOut === true ? 'use no memo' : fn.optOut}".`; category = 'Directive'; policy = true;
+  }
+  const output = { kind: event.kind, status, name: text(fn?.name || event.fnName, root),
+    start: fn?.start || start, end: fn?.end || end, reason, category, policy };
+  if (status === 'optimized') for (const key of ['memoSlots', 'memoBlocks', 'memoValues']) {
+    if (Number.isSafeInteger(event[key]) && event[key] >= 0) output[key] = event[key];
+  }
+  return output;
+}
+
+/** Cache payloads contain code and these immutable event values, never ASTs. */
+export function recordReactCompilerTransform(file, payload, { cacheHit = false } = {}) {
+  const state = reports.getStore();
+  if (!state?.enabled) return;
+  const relative = relativeFile(state.root, file);
+  if (!relative) return;
+  if (!state.files.has(relative) && state.files.size >= FILE_LIMIT) { state.truncated = true; return; }
+  let record = state.files.get(relative);
+  if (!record) state.files.set(relative, record = { file: relative, transforms: 0, cacheReuses: 0,
+    targets: new Set(), notes: new Set(), functions: new Map() });
+  record.transforms++; record.cacheReuses += Number(cacheHit);
+  const target = graphs.getStore() || 'unspecified';
+  record.targets.add(target);
+  for (const note of payload.notes || []) record.notes.add(note);
+  for (const event of payload.events || []) {
+    const key = JSON.stringify([event.start, event.name]);
+    let fn = record.functions.get(key);
+    if (!fn) {
+      if (state.functionCount >= FUNCTION_LIMIT) { state.truncated = true; continue; }
+      record.functions.set(key, fn = { name: event.name, start: event.start, end: event.end,
+        statuses: new Set(), targets: new Set(), events: new Map() });
+      state.functionCount++;
+    }
+    fn.statuses.add(event.status); fn.targets.add(target);
+    const detail = { kind: event.kind, status: event.status, reason: event.reason, category: event.category,
+      ...(event.policy ? { policy: true } : {}), ...Object.fromEntries(['memoSlots', 'memoBlocks', 'memoValues']
+        .filter(key => event[key] !== undefined).map(key => [key, event[key]])) };
+    const detailKey = JSON.stringify(detail);
+    if (fn.events.has(detailKey)) { fn.events.get(detailKey).targets.add(target); continue; }
+    if (fn.events.size < EVENT_LIMIT && state.eventCount < TOTAL_EVENT_LIMIT) { fn.events.set(detailKey, { ...detail, targets: new Set([target]) }); state.eventCount++; }
+    else state.truncated = true;
+  }
+  if (payload.truncated) state.truncated = true;
+}
+export function recordReactCompilerGraph(result) {
+  const state = reports.getStore(), target = graphs.getStore();
+  if (!state?.enabled || !target) return;
+  let record = state.graphs.get(target);
+  if (!record) state.graphs.set(target, record = { target, inputs: new Set(), metadataAvailable: true });
+  if (!result?.metafile?.inputs) { record.metadataAvailable = false; return; }
+  for (const file of Object.keys(result.metafile.inputs)) {
+    if (!/\.(?:[cm]?[jt]s|[jt]sx)$/i.test(file)) continue;
+    const relative = relativeFile(state.root, path.resolve(state.root, file));
+    if (relative && !relative.split('/').some(part => part === 'node_modules' || part.startsWith('.prnext'))) {
+      if (record.inputs.size < GRAPH_INPUT_LIMIT || record.inputs.has(relative)) record.inputs.add(relative);
+      else { state.truncated = true; record.metadataAvailable = false; }
+    }
+  }
+}
+export function reactCompilerReport() {
+  const state = reports.getStore();
+  if (!state) return null;
+  const files = [...state.files.values()].sort((a, b) => a.file.localeCompare(b.file)).map(file => ({
+    file: file.file, transforms: file.transforms, cacheReuses: file.cacheReuses, targets: [...file.targets].sort(), notes: [...file.notes].sort(),
+    functions: [...file.functions.values()].map(fn => ({ name: fn.name, start: fn.start, end: fn.end,
+      status: fn.statuses.size === 1 ? [...fn.statuses][0] : 'mixed', targets: [...fn.targets].sort(),
+      events: [...fn.events.values()].map(({ targets, ...event }) => ({ ...event, targets: [...targets].sort() })) }))
+      .sort((a, b) => (a.start?.line || 0) - (b.start?.line || 0) || (a.start?.column || 0) - (b.start?.column || 0)),
+  }));
+  const summary = summarize(files);
+  return { version: 1, compilerVersion: state.compilerVersion || null, enabled: !!state.enabled,
+    buildId: state.buildId || null, mode: state.dev ? 'development' : 'production', scope: 'observed-transforms',
+    options: state.enabled ? state.options : null, truncated: state.truncated, summary, files,
+    graphs: [...state.graphs.values()].map(graph => ({ target: graph.target, metadataAvailable: graph.metadataAvailable,
+      projectJavaScriptInputs: graph.inputs.size, observedFiles: files.filter(file => file.targets.includes(graph.target)).length,
+      unobservedInputs: [...graph.inputs].filter(file => !state.files.get(file)?.targets.has(graph.target)).length })),
+  };
+}
+
+export async function writeReactCompilerReport(directory, report = reactCompilerReport()) {
+  if (!report) return null;
+  let serialized = JSON.stringify(report) + '\n';
+  // Developer diagnostics must never make an otherwise valid large app fail.
+  while (Buffer.byteLength(serialized) > REPORT_LIMIT && report.files.length) {
+    const files = report.files.slice(0, Math.floor(report.files.length / 2));
+    report = { ...report, truncated: true, files, summary: summarize(files), graphs: report.graphs.map(graph => ({ ...graph,
+      metadataAvailable: false, observedFiles: files.filter(file => file.targets.includes(graph.target)).length,
+      unobservedInputs: graph.projectJavaScriptInputs })) };
+    serialized = JSON.stringify(report) + '\n';
+  }
+  if (Buffer.byteLength(serialized) > REPORT_LIMIT) throw new Error('Invalid React Compiler report metadata.');
+  await mkdir(directory, { recursive: true });
+  await writeFile(path.join(directory, REACT_COMPILER_REPORT_FILE), serialized);
+  return report;
+}
+export async function readReactCompilerReport(directory, { buildId } = {}) {
+  let serialized, handle;
+  try {
+    handle = await open(path.join(directory, REACT_COMPILER_REPORT_FILE), 'r');
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > REPORT_LIMIT) throw new Error('Invalid React Compiler report: size limit exceeded.');
+    const buffer = Buffer.alloc(Math.min(stat.size + 1, REPORT_LIMIT + 1));
+    let length = 0;
+    while (length < buffer.length) {
+      const result = await handle.read(buffer, length, buffer.length - length, length);
+      if (!result.bytesRead) break;
+      length += result.bytesRead;
+    }
+    // A concurrently growing/replaced report is not a successful build artifact.
+    if (length > stat.size || (await handle.stat()).size !== stat.size) throw new Error('Invalid or stale React Compiler report. Rebuild the application.');
+    serialized = buffer.subarray(0, length);
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  finally { await handle?.close(); }
+  let value;
+  try { value = JSON.parse(serialized); } catch { throw new Error('Invalid React Compiler report JSON.'); }
+  if (!validReport(value) || buildId !== undefined && value.buildId !== buildId) throw new Error('Invalid or stale React Compiler report. Rebuild the application.');
+  return value;
+}
+function validReport(report) {
+  const keys = (value, allowed) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => allowed.includes(key));
+  const safePath = file => typeof file === 'string' && file.length <= 1024 && !file.includes('\\') && !/[\u0000-\u001f\u007f]/.test(file)
+    && !path.posix.isAbsolute(file) && !/^[A-Za-z]:/.test(file) && file.split('/').every(part => part && part !== '.' && part !== '..');
+  const boundedText = value => value === null || typeof value === 'string' && value.length <= 384 && !/[\u0000-\u001f\u007f]/.test(value);
+  const count = value => Number.isSafeInteger(value) && value >= 0;
+  const targets = value => Array.isArray(value) && value.length <= 4 && value.every(target => ['browser', 'node', 'edge', 'unspecified'].includes(target));
+  const validPosition = value => value === null || keys(value, ['line', 'column']) && !!position(value);
+  const options = report?.options;
+  const validOptions = options === null || options === true || keys(options, ['compilationMode', 'panicThreshold', 'target'])
+    && ['infer', 'annotation'].includes(options.compilationMode) && ['none', 'critical_errors', 'all_errors'].includes(options.panicThreshold) && options.target === '19';
+  return keys(report, ['version', 'compilerVersion', 'enabled', 'buildId', 'mode', 'scope', 'options', 'truncated', 'summary', 'files', 'graphs'])
+    && report.version === 1 && report.scope === 'observed-transforms' && typeof report.enabled === 'boolean' && validOptions
+    && typeof report.truncated === 'boolean' && ['development', 'production'].includes(report.mode)
+    && boundedText(report.buildId) && boundedText(report.compilerVersion)
+    && keys(report.summary, ['files', 'functions', 'optimized', 'skipped', 'errors', 'diagnostics', 'mixed', 'transforms', 'cacheReuses'])
+    && ['files', 'functions', 'optimized', 'skipped', 'errors', 'diagnostics', 'mixed', 'transforms', 'cacheReuses'].every(key => count(report.summary[key]))
+    && Array.isArray(report.files) && report.files.length <= FILE_LIMIT && report.summary.files === report.files.length
+    && report.files.every(file => file && typeof file === 'object')
+    && new Set(report.files.map(file => file.file)).size === report.files.length
+    && report.files.every(file => keys(file, ['file', 'transforms', 'cacheReuses', 'targets', 'notes', 'functions'])
+      && safePath(file.file) && count(file.transforms) && count(file.cacheReuses) && file.cacheReuses <= file.transforms && targets(file.targets)
+      && Array.isArray(file.notes) && file.notes.length <= 16 && file.notes.every(boundedText)
+      && Array.isArray(file.functions) && file.functions.length <= FUNCTION_LIMIT && file.functions.every(fn => keys(fn, ['name', 'start', 'end', 'status', 'targets', 'events'])
+        && boundedText(fn.name) && statuses.has(fn.status) && validPosition(fn.start) && validPosition(fn.end) && targets(fn.targets)
+        && Array.isArray(fn.events) && fn.events.length <= EVENT_LIMIT && fn.events.every(event => keys(event, ['kind', 'status', 'reason', 'category', 'policy', 'memoSlots', 'memoBlocks', 'memoValues', 'targets'])
+          && kinds.has(event.kind) && statuses.has(event.status) && boundedText(event.reason) && boundedText(event.category) && targets(event.targets)
+          && (event.policy === undefined || typeof event.policy === 'boolean')
+          && ['memoSlots', 'memoBlocks', 'memoValues'].every(key => event[key] === undefined || count(event[key])))))
+    && report.files.reduce((sum, file) => sum + file.functions.length, 0) <= FUNCTION_LIMIT
+    && Object.entries(summarize(report.files)).every(([key, value]) => report.summary[key] === value)
+    && (!report.enabled ? report.files.length === 0 && options === null : options !== null)
+    && Array.isArray(report.graphs) && report.graphs.length <= 4 && report.graphs.every(graph => keys(graph, ['target', 'metadataAvailable', 'projectJavaScriptInputs', 'observedFiles', 'unobservedInputs'])
+      && targets([graph.target]) && typeof graph.metadataAvailable === 'boolean' && ['projectJavaScriptInputs', 'observedFiles', 'unobservedInputs'].every(key => count(graph[key]))
+      && graph.unobservedInputs <= graph.projectJavaScriptInputs);
+}
+function summarize(files) {
+  const summary = { files: files.length, functions: 0, optimized: 0, skipped: 0, errors: 0, diagnostics: 0, mixed: 0, transforms: 0, cacheReuses: 0 };
+  for (const file of files) { summary.transforms += file.transforms; summary.cacheReuses += file.cacheReuses;
+    for (const fn of file.functions) { summary.functions++; summary[({ error: 'errors', diagnostic: 'diagnostics' })[fn.status] || fn.status]++; } }
+  return summary;
+}
+export function printReactCompilerReport(report, { details = false, log = console.log } = {}) {
+  if (!report.enabled) { log('React Compiler: disabled. Enable reactCompiler in the application configuration.'); return; }
+  const summary = report.summary;
+  log(`React Compiler ${report.compilerVersion}: ${summary.optimized} optimized, ${summary.skipped} skipped, ${summary.errors} errors, ${summary.diagnostics} diagnostics, ${summary.mixed} mixed.`);
+  log(`Observed transforms only: ${summary.files} files; ${summary.cacheReuses}/${summary.transforms} transforms reused cached compiler results.${report.truncated ? ' Report truncated at its safety limit.' : ''}`);
+  if (report.graphs.some(graph => graph.unobservedInputs || !graph.metadataAvailable)) log('Some graph inputs were not observed by React Compiler; totals do not describe every application component.');
+  if (details) for (const file of report.files) {
+    log(file.file);
+    for (const fn of file.functions) log(`  ${fn.name || '(anonymous)'}${fn.start ? ':' + fn.start.line : ''}: ${fn.status}${fn.events.some(event => event.reason) ? ' — ' + [...new Set(fn.events.map(event => event.reason).filter(Boolean))].join('; ') : ''}`);
+    for (const note of file.notes) log('  ' + note);
+  }
+}

package/build/react-compiler.mjs

@@ -0,0 +1,139 @@
+import { realpath } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cachedAsyncTransform } from './transform-cache.mjs';
+import { extractSourceMap, inlineSourceMap, sourceMapsEnabled } from './source-maps.mjs';
+import { compilerEvent, recordReactCompilerTransform } from './react-compiler-report.mjs';
+
+const require = createRequire(import.meta.url);
+// Only metadata is loaded here. Disabled builds do not load Babel or the compiler.
+export const REACT_COMPILER_VERSION = require('babel-plugin-react-compiler/package.json').version;
+const BABEL_VERSION = require('@babel/core/package.json').version;
+const frameworkRoot = fileURLToPath(new URL('../', import.meta.url));
+const options = new Set(['compilationMode', 'panicThreshold', 'target']);
+let implementation;
+const REPORT_CACHE_VERSION = 1;
+const optOutDirective = directives => directives?.map(item => item.value.value).find(value => value === 'use no memo' || value === 'use no forget') || false;
+
+function functionLocations(ast) {
+  const functions = [], stack = [{ node: ast.program, parent: null }];
+  while (stack.length && functions.length < 4096) {
+    const { node, parent } = stack.pop();
+    if (!node || typeof node !== 'object' || typeof node.type !== 'string') continue;
+    if (['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'].includes(node.type) && node.loc) {
+      const name = node.id?.name || (parent?.type === 'VariableDeclarator' ? parent.id?.name : null)
+        || (parent?.type === 'ObjectProperty' ? parent.key?.name : null);
+      functions.push({ name: name || null, start: { line: node.loc.start.line, column: node.loc.start.column },
+        end: { line: node.loc.end.line, column: node.loc.end.column },
+        optOut: optOutDirective(node.body?.directives) });
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (['loc', 'extra', 'leadingComments', 'innerComments', 'trailingComments', 'comments', 'tokens'].includes(key)) continue;
+      if (Array.isArray(value)) for (const child of value) stack.push({ node: child, parent: node });
+      else if (value && typeof value === 'object') stack.push({ node: value, parent: node });
+    }
+  }
+  return functions;
+}
+
+/** Deliberately expose only supported, serializable compiler options. */
+export function normalizeReactCompilerConfig(value) {
+  if (value === undefined || value === false) return false;
+  const input = value === true ? {} : value;
+  if (!input || typeof input !== 'object' || Array.isArray(input) || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) {
+    throw new TypeError('reactCompiler must be false, true or an options object.');
+  }
+  for (const key of Reflect.ownKeys(input)) {
+    if (!options.has(key)) throw new TypeError(`reactCompiler.${String(key)} is not supported by PRNext.`);
+  }
+  const compilationMode = input.compilationMode === undefined ? 'infer' : input.compilationMode;
+  const panicThreshold = input.panicThreshold === undefined ? 'none' : input.panicThreshold;
+  const target = input.target === undefined ? '19' : input.target;
+  if (!['infer', 'annotation'].includes(compilationMode)) throw new TypeError('reactCompiler.compilationMode must be infer or annotation.');
+  if (!['none', 'critical_errors', 'all_errors'].includes(panicThreshold)) throw new TypeError('reactCompiler.panicThreshold must be none, critical_errors or all_errors.');
+  if (target !== '19') throw new TypeError("reactCompiler.target must be '19'; PRNext requires React 19.");
+  return Object.freeze({ compilationMode, panicThreshold, target });
+}
+
+function inside(root, filename) {
+  const relative = path.relative(root, filename);
+  return relative !== '' && relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+}
+
+function excluded(root, filename) {
+  if (!inside(root, filename)) return true;
+  const relative = path.relative(root, filename).split(path.sep);
+  return relative.some(part => /^(?:node_modules|\.git|\.next|\.contentlayer|\.prnext|\.prnext-cache|\.prnext-dev|\.prnext-types|out|dist)$/.test(part)
+    || part.startsWith('.prnext-build-') || part.startsWith('.prnext-incremental-'));
+}
+
+function loadImplementation() {
+  implementation ??= Promise.all([import('@babel/core'), import('babel-plugin-react-compiler')]).then(([babel, plugin]) => ({
+    babel, compiler: plugin.default?.default ?? plugin.default,
+  }));
+  return implementation;
+}
+
+/**
+ * Run the official compiler on application source before JSX lowering, React
+ * Refresh and framework instrumentation. JSX/TypeScript/module format remain
+ * intact for the existing graph compiler. No app Babel configuration is loaded.
+ */
+export function createReactCompilerTransform(projectRoot, config, { dev = false } = {}) {
+  const normalized = normalizeReactCompilerConfig(config);
+  if (!normalized) return async source => source;
+  const root = path.resolve(projectRoot);
+  const canonicalRoot = realpath(root).catch(error => {
+    if (error.code === 'ENOENT') return root;
+    throw error;
+  });
+  const canonicalFramework = realpath(frameworkRoot).catch(() => frameworkRoot);
+  return async (source, filename, { loaderOutput = false } = {}) => {
+    filename = path.resolve(filename);
+    if ((!loaderOutput && !/\.(?:[cm]?[jt]s|[jt]sx)$/i.test(filename)) || /\.d\.[cm]?ts$/i.test(filename)) return source;
+    const actualRoot = await canonicalRoot;
+    if (excluded(root, filename) && excluded(actualRoot, filename)) return source;
+    // Bundlers canonicalize linked project roots. Also resolve linked source
+    // files so a project symlink cannot pull dependencies/framework/generated
+    // files into the application compiler accidentally.
+    const actualFile = await realpath(filename).catch(error => {
+      if (error.code === 'ENOENT') return inside(root, filename) ? path.resolve(actualRoot, path.relative(root, filename)) : filename;
+      throw error;
+    });
+    if (excluded(actualRoot, actualFile) || inside(await canonicalFramework, actualFile)) return source;
+    let cacheHit = true;
+    const serialized = await cachedAsyncTransform('react-compiler-report', source,
+      [REPORT_CACHE_VERSION, REACT_COMPILER_VERSION, BABEL_VERSION, normalized, root, actualRoot, filename, actualFile, !!dev, !!loaderOutput], async () => {
+        cacheHit = false;
+        const { babel, compiler } = await loadImplementation();
+        const mapped = sourceMapsEnabled();
+        const { code, map } = extractSourceMap(source);
+        const syntax = { filename, babelrc: false, configFile: false, sourceType: 'unambiguous',
+          parserOpts: { plugins: ['jsx', ...(/\.(?:[cm]?ts|tsx)$/i.test(filename) ? ['typescript'] : [])] } };
+        const ast = await babel.parseAsync(code, syntax);
+        // Server Action files are executable server modules, not render graphs.
+        if (ast.program.directives.some(item => item.value.value === 'use server')) return JSON.stringify({ code: source, events: [], notes: ['Server Action module excluded.'] });
+        const functions = functionLocations(ast), events = [], notes = [];
+        const moduleOptOut = optOutDirective(ast.program.directives);
+        if (moduleOptOut) notes.push(`Module uses "${moduleOptOut}"; compiled functions are not emitted.`);
+        if (normalized.compilationMode === 'annotation') notes.push('Annotation mode only selects functions with "use memo". Unselected functions have no compiler events.');
+        if (loaderOutput) notes.push('Locations refer to JavaScript produced by the configured loader.');
+        let truncated = false;
+        const logger = { logEvent(_filename, event) {
+          const value = compilerEvent(event, functions, { moduleOptOut, root });
+          if (value) { if (events.length < 256) events.push(value); else truncated = true; }
+        } };
+        const result = await babel.transformFromAstAsync(ast, code, { ...syntax, cloneInputAst: false,
+          sourceMaps: mapped, sourceFileName: filename, inputSourceMap: mapped ? map ?? false : false,
+          // Boundary checks above use real path segments. Avoid the plugin's
+          // default substring test rejecting e.g. /my-node_modules-example/.
+          plugins: [[compiler, { ...normalized, sources: null, logger }]],
+        });
+        return JSON.stringify({ code: mapped ? inlineSourceMap(result.code, result.map) : result.code, events, notes, truncated });
+      });
+    const payload = JSON.parse(serialized);
+    recordReactCompilerTransform(inside(root, filename) ? filename : path.resolve(root, path.relative(actualRoot, actualFile)), payload, { cacheHit });
+    return payload.code;
+  };
+}

package/build/runtime-contract.mjs

@@ -5,12 +5,12 @@ import path from 'node:path';
 // Protocol compatibility does not imply safe retirement. These modules jointly
 // implement activity tracking, cancellation and post-response draining.
 export const lifecycleModules = ['worker.mjs', 'transport.mjs', 'request-work.mjs', 'app-render.mjs', 'app-stream-html.mjs', 'rsc-worker.mjs'];
-export async function writeRuntimeContract(stage) {
+export async function writeRuntimeContract(stage, {deployment=false,htmlOnly=false,workerMemory=false,incrementalCache=false} = {}) {
   const files = (await Promise.all(['runtime', 'compat'].map(async directory =>
     (await readdir(path.join(stage,directory))).filter(name => /\.(?:mjs|cjs|json)$/.test(name)).map(name => `${directory}/${name}`)))).flat().sort();
   const modules = Object.fromEntries(await Promise.all(files.map(async name =>
     [name, createHash('sha256').update(await readFile(path.join(stage, name))).digest('hex')])));
-  const contract = { schema: 1, protocol: 2, lifecycle: 1,
+  const contract = { schema: 1, protocol: 2, lifecycle: 1, ...(deployment ? {deployment:1} : {}), ...(htmlOnly ? {htmlOnly:1} : {}), ...(workerMemory ? {workerMemory:1} : {}), ...(incrementalCache ? {incrementalCache:1} : {}),
     capabilities: ['activity', 'tracked-finalization', 'graceful-drain', 'lane-cancellation'], modules };
   await writeFile(path.join(stage, 'runtime-contract.json'), JSON.stringify(contract, null, 2) + '\n');
 }

package/build/static-export.mjs

@@ -65,16 +65,16 @@ export async function prepareStaticExport({ project, stage, manifest, config })
     if (route?.kind === 'api') { await put(mount + pathname, body); continue; }
     let html = body.toString();
     if (html.includes(config.images.path + '?')) reject(`optimized images in ${pathname} require images.unoptimized or a custom loader`);
-    html = html.replace(/<head(?:\s[^>]*)?>/i, value => value + '<script>window.__PRNEXT_STATIC_EXPORT__=true;</script>');
+    if (!route.htmlOnly) html = html.replace(/<head(?:\s[^>]*)?>/i, value => value + '<script>window.__PRNEXT_STATIC_EXPORT__=true;</script>');
     const output = pathname === '/' ? '/index.html' : config.trailingSlash && !['/404', '/500'].includes(pathname) ? pathname + '/index.html' : pathname + '.html';
     await put(mount + output, html);
     if (entry.dataFile) {
       const data = await readFile(path.join(stage, entry.dataFile));
-      if (route?.router === 'app') await put(mount + '/_prnext/flight' + (pathname === '/' ? '' : pathname) + '/index.txt', data);
-      else for (const prefix of ['/_prnext/data/', '/_next/data/']) await put(mount + prefix + manifest.buildId + (pathname === '/' ? '/index' : pathname) + '.json', data);
+      if (route?.router === 'app') await put(mount + '/_prnext/flight' + (manifest.config.deploymentId ? '/' + encodeURIComponent(manifest.config.deploymentId) : '') + (pathname === '/' ? '' : pathname) + '/index.txt', data);
+      else for (const prefix of ['/_prnext/data/', '/_next/data/']) await put(mount + prefix + encodeURIComponent(manifest.config.deploymentId ? manifest.buildId + '~' + manifest.config.deploymentId : manifest.buildId) + (pathname === '/' ? '/index' : pathname) + '.json', data);
     }
   }
-  await writeFile(path.join(folder, marker), JSON.stringify({ version: 1, buildId: manifest.buildId, basePath: mount, trailingSlash: config.trailingSlash }));
+  await writeFile(path.join(folder, marker), JSON.stringify({ version: 1, buildId: manifest.buildId, deploymentId: manifest.config.deploymentId, basePath: mount, trailingSlash: config.trailingSlash }));
   return folder;
 }
 

package/build/styles.mjs

@@ -39,10 +39,12 @@ async function loadConfiguration(root) {
   return /\.(?:js|mjs|cjs)$/.test(filename) ? importConfiguration(filename) : JSON.parse(await readFile(filename, 'utf8'));
 }
 
-async function createProcessor(root, engine) {
+export const resolveStandardBrowserTargets = root => browserslist(undefined,{path:path.resolve(root)});
+
+async function createProcessor(root, engine, browserTargets) {
   const config = await loadConfiguration(root);
   if (config === undefined && engine !== 'postcss') {
-    const targets=browserslistToTargets(browserslist(undefined,{path:root}));
+    const targets=browserslistToTargets(browserTargets ? await browserTargets() : resolveStandardBrowserTargets(root));
     return {async process(css,options){
       const result=transformCss({filename:options.from,code:Buffer.from(css),targets,minify:false,sourceMap:!!options.map,
         ...(options.map?.prev ? {inputSourceMap:JSON.stringify(options.map.prev)} : {}),drafts:{customMedia:true}});
@@ -134,7 +136,7 @@ function packageImporter(require) {
 }
 
 /** Build-only transformations, shared and deduplicated across all three React graphs. */
-export function createStyleProcessor({ projectRoot, sassOptions = {}, cssEngine = 'auto' }) {
+export function createStyleProcessor({ projectRoot, sassOptions = {}, cssEngine = 'auto', browserTargets }) {
   const root = path.resolve(projectRoot);
   const require = createRequire(path.join(root, 'package.json'));
   const cache = new Map();
@@ -168,7 +170,7 @@ export function createStyleProcessor({ projectRoot, sassOptions = {}, cssEngine
       sourceMap = compiled.sourceMap;
       for (const url of compiled.loadedUrls) if (url.protocol === 'file:') dependencies.add(fileURLToPath(url));
     }
-    processor ??= createProcessor(root,cssEngine);
+    processor ??= createProcessor(root,cssEngine,browserTargets);
     const processed = await (await processor).process(css, { from: file, to: file, map: sourceMap ? { prev: sourceMap, inline: false, annotation: false } : false });
     for (const message of processed.messages) if (message.type === 'dependency' && message.file) dependencies.add(path.resolve(root, message.file));
     rebaseReferences(processed.root, file);

package/build/transform.mjs

@@ -51,7 +51,7 @@ export async function rewriteServerChunks(file,chunks,publicPath){
 }
 
 function parserOptions(filename) {
-  return { sourceType: 'unambiguous', sourceFilename: filename, plugins: ['jsx', ...( /\.tsx?$/.test(filename) ? ['typescript'] : [])] };
+  return { sourceType: 'unambiguous', sourceFilename: filename, plugins: ['jsx', ...( /\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] };
 }
 
 export function assertSupportedSource(source, filename) {

package/build/typed-routes.mjs

@@ -3,6 +3,8 @@ import {createRequire} from 'node:module';
 import {randomUUID} from 'node:crypto';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {resolveTypeScript} from './typescript-toolchain.mjs';
+import {nativeTypeConfig} from './native-type-config.mjs';
 
 const marker='// Generated by PRNext: typed route registry. Do not edit.';
 async function changed(file,contents,updates){
@@ -52,6 +54,8 @@ async function bindTypes(filename,ts,updates){
 async function includeTypes(root,config,helper,updates){
   const filename=path.resolve(root,config.typescript?.tsconfigPath||'tsconfig.json');
   const source=await readFile(filename,'utf8').catch(error=>{if(error.code==='ENOENT')return;throw error;});if(source===undefined)return;
+  const toolchain=await resolveTypeScript(root);
+  if(toolchain.native){await changed(filename,await nativeTypeConfig(filename,helper),updates);return;}
   let ts;try{ts=createRequire(path.join(root,'package.json'))('typescript');}catch{throw Error('typedRoutes requires TypeScript installed in the application');}
   const parsed=ts.getParsedCommandLineOfConfigFile(filename,{noEmit:true},{...ts.sys,onUnRecoverableConfigFileDiagnostic:diagnostic=>{throw Error(ts.flattenDiagnosticMessageText(diagnostic.messageText,'\n'));}});
   if(!parsed||parsed.errors.some(error=>error.code!==18003))throw Error('Cannot configure typed routes: invalid tsconfig');

package/build/typescript-dev.mjs

@@ -1,22 +1,49 @@
 import {fork} from 'node:child_process';
 import {access} from 'node:fs/promises';
-import {createRequire} from 'node:module';
+import {resolveTypeScript} from './typescript-toolchain.mjs';
 import path from 'node:path';
 import {privateCacheDirectory} from './persistent-cache.mjs';
-export async function startTypeChecker(root,config,notify){
+export async function startTypeChecker(root,config,notify,{fork:spawnChecker=fork,recheckDelayMs=3000}={}){
   const noop={inactive:true,async close(){}};
   if(config.typescript?.devChecks===false)return noop;
   const filename=path.resolve(root,config.typescript?.tsconfigPath||'tsconfig.json');try{await access(filename);}catch{return noop;}
-  let compiler;try{compiler=createRequire(path.join(root,'package.json')).resolve('typescript');}catch{console.warn('TypeScript diagnostics require typescript installed in the application.');return noop;}
+  let toolchain;try{toolchain=await resolveTypeScript(root);}catch(error){console.warn('TypeScript diagnostics could not start: '+error.message);return noop;}
   const directory=await privateCacheDirectory(root,'typescript-dev');
-  let child,closed=false,failures=0,timer;
+  let child,closed=false,failures=0,timer,restartTimer,planned,pendingInvalidation;
   function launch(){
     if(closed)return;
-    child=fork(new URL('./typescript-dev-worker.mjs',import.meta.url),[compiler,filename,directory?path.join(directory,'project.tsbuildinfo'):''],{cwd:root,execArgv:['--max-old-space-size=512'],stdio:['ignore','ignore','pipe','ipc'],windowsHide:true});
+    const worker=toolchain.native?'./typescript-native-worker.mjs':'./typescript-dev-worker.mjs';
+    child=spawnChecker(new URL(worker,import.meta.url),[toolchain.compiler,filename,toolchain.native?'watch':directory?path.join(directory,'project.tsbuildinfo'):''],{cwd:root,execArgv:['--max-old-space-size=512'],stdio:['ignore','ignore','pipe','ipc'],windowsHide:true});
+    const current=child;
     let details='',healthyAt=0;child.stderr.on('data',chunk=>{details=(details+chunk).slice(-2048);});
-    child.on('message',message=>{if(message?.type==='diagnostics'&&Array.isArray(message.errors)){healthyAt ||= Date.now();notify(message.errors.filter(value=>typeof value==='string').slice(0,40));}});
+    child.on('message',message=>{
+      if(closed||child!==current||planned===current)return;
+      if(message?.type==='diagnostics'&&Array.isArray(message.errors)){
+        // The native watcher normally handles edits incrementally. Its startup
+        // can miss an edit; retain one bounded fallback when no report arrives.
+        if(pendingInvalidation?.worker===current&&!pendingInvalidation.forced){clearTimeout(restartTimer);pendingInvalidation=undefined;}
+        healthyAt ||= Date.now();notify(message.errors.filter(value=>typeof value==='string').slice(0,40));
+      }
+    });
     child.on('error',error=>{notify(['TypeScript checker: '+error.message]);});
-    child.once('exit',()=>{if(closed)return;if(healthyAt&&Date.now()-healthyAt>=60000)failures=0;if(++failures>=3){notify(['TypeScript checker stopped after repeated failures. '+details]);return;}timer=setTimeout(launch,1000*failures);});
+    child.once('exit',()=>{
+      if(pendingInvalidation?.worker===current){clearTimeout(restartTimer);pendingInvalidation=undefined;}
+      if(closed)return;if(planned===current){planned=undefined;launch();return;}if(healthyAt&&Date.now()-healthyAt>=60000)failures=0;if(++failures>=3){notify(['TypeScript checker stopped after repeated failures. '+details]);return;}timer=setTimeout(launch,1000*failures);
+    });
   }
-  launch();return {async close(){closed=true;clearTimeout(timer);const old=child;if(!old||old.exitCode!==null||old.signalCode)return;await new Promise(resolve=>{const timer=setTimeout(()=>old.kill('SIGKILL'),3000);old.once('exit',()=>{clearTimeout(timer);resolve();});if(old.connected)old.disconnect();else old.kill();});}};
+  launch();return {
+    invalidate(file,event){
+      if(!toolchain.native||closed||!child?.connected)return;
+      const extension=path.extname(file);if(extension&&!/^\.(?:[cm]?[jt]sx?|json)$/i.test(extension))return;
+      const forced=event==='rename'||/\.json$/i.test(file);
+      if(!forced&&event!=='change')return;
+      clearTimeout(restartTimer);
+      const pending={worker:child,forced:forced||pendingInvalidation?.forced===true};pendingInvalidation=pending;
+      restartTimer=setTimeout(()=>{
+        if(closed||pendingInvalidation!==pending||child!==pending.worker||!child?.connected)return;
+        pendingInvalidation=undefined;planned=child;child.disconnect();
+      },pending.forced?150:recheckDelayMs);
+    },
+    async close(){closed=true;clearTimeout(timer);clearTimeout(restartTimer);const old=child;if(!old||old.exitCode!==null||old.signalCode)return;await new Promise(resolve=>{const timer=setTimeout(()=>old.kill('SIGKILL'),5000);old.once('exit',()=>{clearTimeout(timer);resolve();});if(old.connected)old.disconnect();else old.kill();});},
+  };
 }

package/build/typescript-native-worker.mjs

@@ -0,0 +1,55 @@
+import {spawn} from 'node:child_process';
+import {StringDecoder} from 'node:string_decoder';
+import {mkdtemp,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+
+const [compiler,filename,mode]=process.argv.slice(2);
+const watching=mode==='watch';
+let closing=false,buffer='',output='',overflow=false;
+const cache=await mkdtemp(path.join(tmpdir(),'prnext-typescript-native-'));
+const child=spawn(process.execPath,[compiler,'--project',filename,'--noEmit','--incremental','true','--tsBuildInfoFile',path.join(cache,'project.tsbuildinfo'),'--pretty','false','--locale','en',...(watching?['--watch','--preserveWatchOutput']:[])],{
+  cwd:process.cwd(),windowsHide:true,detached:process.platform!=='win32',stdio:['ignore','pipe','pipe'],
+  // Native TS respects explicit project watch options. The polling defaults
+  // also cover editors/filesystems that silently lose native watch events.
+  env:{...process.env,TSC_WATCHFILE:process.env.TSC_WATCHFILE||'DynamicPriorityPolling',TSC_WATCHDIRECTORY:process.env.TSC_WATCHDIRECTORY||'DynamicPriorityPolling'},
+});
+function send(value){if(process.connected)process.send(value);}
+function consume(chunk){
+  const text=chunk.toString('utf8').replace(/\x1b\[[0-9;]*[A-Za-z]/g,'');
+  if(!watching){output+=text;if(output.length>4*1024*1024){overflow=true;void close();}return;}
+  buffer+=text;
+  // Consume complete lines, not arbitrary OS chunks. Start/completion markers
+  // delimit each diagnostic generation; a successful edit clears old errors.
+  let end;
+  while((end=buffer.indexOf('\n'))!==-1){
+    const line=buffer.slice(0,end).replace(/\r$/,'');buffer=buffer.slice(end+1);
+    if(/Starting (?:incremental )?compilation in watch mode|File change detected/.test(line))output='';
+    else if(/Found \d+ errors?\. Watching for file changes\./.test(line)){
+      send({type:'diagnostics',errors:/Found 0 errors/.test(line)?[]:output.trim()?[output.trim()]:['TypeScript reported errors. Run prnext typecheck for details.']});output='';
+    }else if(line.trim()&&output.length<20000)output+=(line+'\n').slice(0,20000-output.length);
+  }
+  if(buffer.length>20000)buffer=buffer.slice(-20000);
+}
+for(const stream of [child.stdout,child.stderr]){
+  const decoder=new StringDecoder('utf8');stream.on('data',chunk=>consume(decoder.write(chunk)));stream.on('end',()=>consume(decoder.end()));
+}
+child.once('error',error=>{send({type:'failure',message:error.message});process.exitCode=1;});
+child.once('close',async(code,signal)=>{
+  // Only the directory returned by mkdtemp above is removed.
+  if(path.dirname(cache)===path.resolve(tmpdir())&&path.basename(cache).startsWith('prnext-typescript-native-'))await rm(cache,{recursive:true,force:true,maxRetries:5,retryDelay:100});
+  send({type:'complete',code:overflow?1:code??1,output:overflow?'TypeScript output exceeded 4 MiB. Run tsc directly for the complete output.':output,signal});
+  if(process.connected)process.disconnect();
+});
+async function close(){
+  if(closing)return;closing=true;
+  if(child.exitCode!==null||child.signalCode)return;
+  if(process.platform==='win32'){
+    // Own exactly this compiler subtree; TypeScript's official Node launcher
+    // starts its native executable as a child on Windows.
+    const killer=spawn('taskkill',['/PID',String(child.pid),'/T','/F'],{windowsHide:true,stdio:'ignore'});
+    killer.on('error',()=>child.kill('SIGKILL'));
+  }else{try{process.kill(-child.pid,'SIGTERM');}catch{child.kill('SIGTERM');}}
+}
+process.once('disconnect',()=>{void close();});
+process.once('SIGTERM',()=>{void close();});process.once('SIGINT',()=>{void close();});

package/build/typescript-native.mjs

@@ -0,0 +1,18 @@
+import {fork} from 'node:child_process';
+
+export function checkNativeTypeScript(compiler,filename,root){
+  return new Promise((resolve,reject)=>{
+    const child=fork(new URL('./typescript-native-worker.mjs',import.meta.url),[compiler,filename,'check'],{cwd:root,windowsHide:true,execArgv:[],stdio:['ignore','ignore','pipe','ipc']});
+    let result,details='',timedOut=false,force;
+    const deadline=setTimeout(()=>{timedOut=true;if(child.connected)child.disconnect();force=setTimeout(()=>child.kill('SIGKILL'),5000);},120000);
+    child.stderr.on('data',chunk=>{details=(details+chunk).slice(-8192);});
+    child.on('message',message=>{if(message?.type==='complete')result=message;else if(message?.type==='failure')details=String(message.message).slice(0,8192);});
+    child.once('error',error=>{clearTimeout(deadline);clearTimeout(force);reject(error);});
+    child.once('exit',()=>{
+      clearTimeout(deadline);clearTimeout(force);
+      if(timedOut)reject(new Error('TypeScript check exceeded 120 seconds. Run tsc directly to inspect the project.'));
+      else if(result?.code===0)resolve();
+      else reject(new Error(result?.output||details||'TypeScript native checker exited before returning diagnostics.'));
+    });
+  });
+}