@thomas.f/prnext 0.1.16-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/scan.mjs

@@ -51,7 +51,7 @@ function validatePattern(segments, relativeFile) {
   return pattern;
 }
 
-export async function scanProject(projectRoot, { basePath = '', pageExtensions, i18n } = {}) {
+export async function scanProject(projectRoot, { basePath = '', pageExtensions, i18n, devAppFiles } = {}) {
   const sourceExtension = pageExtensionPattern(pageExtensions);
   const root = path.resolve(projectRoot);
   const middleware = await scanMiddleware(root, { basePath, pageExtensions, i18n });
@@ -96,7 +96,7 @@ export async function scanProject(projectRoot, { basePath = '', pageExtensions,
     });
   }
   const appRoot = appRoots[0];
-  const { appNotFound, appGlobalError } = appRoot ? await scanAppRoutes({ root, appRoot, routes, patterns, sourceExtension, pageExtensions }) : {};
+  const { appNotFound, appGlobalError } = appRoot ? await scanAppRoutes({ root, appRoot, routes, patterns, sourceExtension, pageExtensions, devAppFiles }) : {};
   const metadataManifest = appRoot ? await scanMetadataRoutes({ root, appRoot, files: await walk(appRoot), routes, patterns, validatePattern, basePath, pageExtensions, appNotFound }) : undefined;
   if (metadataManifest) for (const route of routes) if (route.router === 'app' && route.kind === 'page') route.staticMetadata = { manifest: metadataManifest };
   if (!routes.length && !appNotFound) throw new Error('No page or API route found in the Pages Router or App Router directories.');
@@ -108,7 +108,7 @@ const appConventions = new Map([
   ['loading', 'loading'], ['error', 'error'], ['not-found', 'notFound'], ['default', 'default'],
 ]);
 
-async function scanAppRoutes({ root, appRoot, routes, patterns, sourceExtension, pageExtensions = defaultPageExtensions }) {
+async function scanAppRoutes({ root, appRoot, routes, patterns, sourceExtension, pageExtensions = defaultPageExtensions, devAppFiles }) {
   const directories = new Map();
   const configs = new Map();
   let appGlobalError;
@@ -135,7 +135,7 @@ async function scanAppRoutes({ root, appRoot, routes, patterns, sourceExtension,
     const descriptor = directories.get(directory) || { directory, files: {} };
     const name = appConventions.get(filename);
     if (descriptor.files[name]) { console.warn(`Duplicate ${filename} file ${relative}; using ${path.relative(appRoot, descriptor.files[name])} according to pageExtensions.`); continue; }
-    if (['page', 'layout', 'route'].includes(filename)) configs.set(file, await validateAppConfig(file));
+    if (['page', 'layout', 'route'].includes(filename)) configs.set(file, !devAppFiles || devAppFiles.has(file) ? await validateAppConfig(file) : {});
     descriptor.files[name] = file;
     directories.set(directory, descriptor);
   }

package/build/source-analysis.mjs

@@ -0,0 +1,42 @@
+import {parseSync} from 'oxc-parser';
+import {createHash} from 'node:crypto';
+
+// Read-only analyses share one Rust parse. Transformations still use Babel's
+// binding-aware AST: ESTree nodes must never be passed to Babel transforms.
+const cache=new Map();
+let bytes=0,hits=0,misses=0;
+export const sourceAnalysisStats=()=>({entries:cache.size,bytes,hits,misses});
+export function analyzeSource(source,file='source.js') {
+  const key=file+'\0'+createHash('sha256').update(source).digest('hex');
+  if(cache.has(key)){const hit=cache.get(key);cache.delete(key);cache.set(key,hit);hits++;return hit.value;}
+  misses++;
+  const parsed=parseSync(file,source,{sourceType:'unambiguous',allowReturnOutsideFunction:true});
+  if(parsed.errors.length)throw new SyntaxError(`${file}: ${parsed.errors.map(error=>error.message).join('; ')}`);
+  const program=parsed.program,directives=[];
+  for(const node of program.body){if(!node.directive)break;directives.push(node.directive);}
+  const imports=[];
+  let computedRequire=false;
+  const pending=[program];
+  while(pending.length){
+    const node=pending.pop();
+    if(['ImportDeclaration','ExportNamedDeclaration','ExportAllDeclaration'].includes(node.type)&&node.source&&node.importKind!=='type'&&node.exportKind!=='type')imports.push({path:node.source.value,kind:'import-statement'});
+    if(node.type==='ImportExpression'&&typeof node.source?.value==='string')imports.push({path:node.source.value,kind:'dynamic-import'});
+    if(node.type==='CallExpression'&&node.callee?.type==='Identifier'&&node.callee.name==='require'){
+      const argument=node.arguments[0];
+      if(argument?.type==='Literal'&&typeof argument.value==='string')imports.push({path:argument.value,kind:'require-call'});else computedRequire=true;
+    }
+    for(const value of Object.values(node)){
+      if(Array.isArray(value)){for(let i=value.length-1;i>=0;i--)if(value[i]?.type)pending.push(value[i]);}
+      else if(value&&typeof value==='object'&&value.type)pending.push(value);
+    }
+  }
+  const value={program,directives,imports,computedRequire,frameworkBoundary:directives.some(item=>item==='use client'||item==='use server')};
+  // ASTs are substantially larger than source. Bound both count and estimated
+  // retained size; large individual npm modules are analyzed without retention.
+  const size=Buffer.byteLength(source)*16+Buffer.byteLength(file);
+  if(size<=4*1024*1024){
+    while(cache.size&&(cache.size>=64||bytes+size>16*1024*1024)){const [old,hit]=cache.entries().next().value;cache.delete(old);bytes-=hit.size;}
+    cache.set(key,{value,size});bytes+=size;
+  }
+  return value;
+}

package/build/static-adapter.mjs

@@ -7,6 +7,7 @@ import { OUTPUT_POINTER, prepareBuildDirectory, readBuildDirectory, validateDist
 import { writeBuildOutput } from './output-contract.mjs';
 import { precompressBuild } from './precompress.mjs';
 import { withBuildLock } from './build-lock.mjs';
+import { plainStaticPath } from './static-input.mjs';
 
 const MAX_FILES = 20000, MAX_BYTES = 512 * 1024 * 1024;
 const inside = (root, file) => file.startsWith(root + path.sep);
@@ -23,17 +24,18 @@ async function importStatic(directory, { from, spa, distDir, dev }) {
   const root = await realpath(directory);
   // Reuse the output-directory restrictions to keep imports within this project
   // and away from source/dependency/repository trees.
-  const relative = validateDistDir(from);
+  const rootInput = from === '.';
+  const relative = rootInput ? '.' : validateDistDir(from);
   const output = distDir === undefined ? await readBuildDirectory(root) : validateDistDir(distDir);
   const source = path.join(root, relative), destination = await prepareBuildDirectory(root, output);
-  if (source === destination || inside(source, destination) || inside(destination, source)) throw new Error('Static input and PRNext output directories must not overlap.');
+  if (!rootInput && (source === destination || inside(source, destination) || inside(destination, source))) throw new Error('Static input and PRNext output directories must not overlap.');
   let ancestor = root;
-  for (const part of relative.split('/')) {
+  for (const part of rootInput ? [] : relative.split('/')) {
     ancestor = path.join(ancestor, part);
     const entry = await lstat(ancestor);
     if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error('Static input must use real directories, not symbolic links.');
   }
-  if (!inside(root, await realpath(source))) throw new Error('Static input must stay inside the project.');
+  if (!rootInput && !inside(root, await realpath(source))) throw new Error('Static input must stay inside the project.');
   const index = await lstat(path.join(source, 'index.html')).catch(() => null);
   if (!index?.isFile() || index.isSymbolicLink()) throw new Error('Static input needs index.html. Run your framework build first and select its public output with --from.');
 
@@ -50,12 +52,18 @@ async function importStatic(directory, { from, spa, distDir, dev }) {
   async function copy(folder = '', depth = 0) {
     if (depth > 64) throw new Error('Static input exceeds 64 directory levels.');
     for (const name of (await readdir(path.join(source, folder))).sort()) {
+      const file = folder ? `${folder}/${name}` : name;
+      if (rootInput && (!plainStaticPath(file, true) || file === output || file.startsWith(output + '/'))) continue;
+      if (rootInput) {
+        const entry = await lstat(path.join(source, file));
+        if (entry.isSymbolicLink()) throw new Error(`Static input cannot contain symbolic links: ${file}`);
+        if (!entry.isDirectory() && !plainStaticPath(file)) continue;
+      }
       if (name.includes('\\') || /[\x00-\x1f\x7f:]/.test(name) ||
           name.startsWith('.') && !(folder === '' && name === '.well-known') ||
           ['node_modules', '_prnext', '_next'].includes(name) || folder === '' && name === 'server') {
         throw new Error(`Static input contains a private, reserved or server path: ${folder ? folder + '/' : ''}${name}. Select only browser-ready files.`);
       }
-      const file = folder ? `${folder}/${name}` : name;
       const entry = await lstat(path.join(source, file));
       if (entry.isSymbolicLink()) throw new Error(`Static input cannot contain symbolic links: ${file}`);
       if (entry.isDirectory()) { await copy(file, depth + 1); continue; }

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/static-input.mjs

@@ -0,0 +1,48 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const outputs = ['dist', 'build', 'out', '.output/public'];
+async function file(root, name) {
+  try { const entry = await lstat(path.join(root, name)); return entry.isFile() && !entry.isSymbolicLink(); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false; throw error; }
+}
+
+/** Root imports deliberately publish browser assets only, never a project tree. */
+export function plainStaticPath(file, directory = false) {
+  const parts = file.split('/'), name = parts.at(-1);
+  if (parts.some(part => part.startsWith('.') && part !== '.well-known' ||
+      /^(?:node_modules|server|api|functions|config|src|app|pages|components|lib|packages|tests?|coverage|dist|build|out)$/i.test(part))) return false;
+  if (directory) return true;
+  if (/(?:^|[.-])(?:config|server|test|spec)(?:[.-]|$)/i.test(name)) return false;
+  if (parts[0] === '.well-known') return /\.(?:txt|json)$/.test(name);
+  return /\.(?:html?|css|js|mjs|wasm|webmanifest|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf|eot|mp4|webm|mp3|ogg|wav|pdf)$/i.test(name) || /^(?:robots|ads|security)\.txt$/i.test(name);
+}
+
+/** Inspect metadata only; never execute a framework config or build command. */
+export async function detectBuildAdapter(root, { prepared = false } = {}) {
+  let manifest = {};
+  try {
+    const contents = await readFile(path.join(root, 'package.json'));
+    if (contents.length > 256 * 1024) throw new Error('package.json exceeds 256 KiB');
+    manifest = JSON.parse(contents);
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw new Error('Invalid package.json');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const deps = { ...manifest.devDependencies, ...manifest.dependencies };
+  if ('next' in deps) return { adapter: 'react' };
+  // A Vite index.html is source, and must not be mistaken for a completed site.
+  const builder = ['vite', 'astro', '@sveltejs/kit', 'nuxt', 'react-scripts', '@angular/core', '@tanstack/react-start', '@tanstack/solid-start'].some(name => name in deps);
+  if (!builder) for (const name of ['app', 'pages', 'src/app', 'src/pages']) {
+    try { if ((await lstat(path.join(root, name))).isDirectory()) return { adapter: 'react' }; }
+    catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error; }
+  }
+  const script = manifest.scripts?.build;
+  if (!builder && (!script || /^(?:prnext|prn) build(?:\s|$)/.test(script)) && await file(root, 'index.html')) return { adapter: 'static', from: '.' };
+  if (prepared) {
+    const found = [];
+    for (const from of outputs) if (await file(root, from + '/index.html')) found.push(from);
+    if (found.length > 1) throw new Error('Multiple static outputs found. Select one with --adapter static --from <directory>.');
+    if (found.length === 1) return { adapter: 'static', from: found[0] };
+    throw new Error('No completed browser build found. Run your framework build, then use --adapter static --from <directory>. Plain HTML sites need index.html at the root.');
+  }
+  return { adapter: 'react' };
+}