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

package/build/prerender-pages.mjs

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {writeFile} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import {localizedStaticPaths} from './i18n.mjs';
+import {mapConcurrent} from './concurrent.mjs';
+const isDynamic=pattern=>pattern.includes('[');
+
+export async function prerenderPages(stage, manifest, dev) {
+  // Development renders on demand. Do not load a fresh renderer or execute
+  // getStaticProps/getStaticPaths for every route on every edit.
+  const renderer = dev ? null : await import(pathToFileURL(path.join(stage, 'runtime/render.mjs')).href);
+  const paths = new Set();
+  const seedsByRoute = new Map();
+  const validatedDocuments = new Set();
+  const staticListings = new Map();
+  // Error page data is available when another static page returns notFound.
+  const ordered = [...manifest.routes].sort((left, right) => Number(!!right.errorStatus) - Number(!!left.errorStatus));
+  async function renderRoute(route) {
+    if (route.kind !== 'page' || route.router === 'app') return;
+    const modulePath = path.join(stage, route.module);
+    const page = await import(pathToFileURL(modulePath).href);
+    if (page.__prnextDocument && !validatedDocuments.has(page.__prnextDocument)) {
+      for (const name of ['getStaticProps', 'getStaticPaths', 'getServerSideProps']) {
+        if (Object.hasOwn(page.__prnextDocument, name) || typeof page.Document?.[name] === 'function') throw new Error(`pages/_document does not support ${name}. Use Document.getInitialProps for server document rendering.`);
+      }
+      validatedDocuments.add(page.__prnextDocument);
+    }
+    if (route.errorStatus && (page.getServerSideProps || page.default?.getInitialProps)) throw new Error(`pages${route.pattern} must be static and cannot use getServerSideProps or getInitialProps. Use getStaticProps instead.`);
+    route.gip = typeof page.default?.getInitialProps === 'function';
+    route.appGip = !!page.App && page.App.getInitialProps !== page.App.origGetInitialProps;
+    if (route.internal && route.errorStatus && route.appGip) {
+      // A custom App hook makes the built-in Error request-dependent. Select
+      // its actual _error module so the default status props and visible URL
+      // reach App.getInitialProps instead of a synthetic static wrapper.
+      const kind = route.errorStatus === 404 ? 'notFound' : 'serverError';
+      if (manifest.pagesErrors?.[kind] === route.id) delete manifest.pagesErrors[kind];
+    }
+    if (route.gip && (page.getStaticProps || page.getServerSideProps)) throw new Error(`Page ${route.pattern} cannot combine getInitialProps with getStaticProps or getServerSideProps.`);
+    if (route.internal && !route.errorStatus) {
+      if (page.getStaticProps || page.getServerSideProps || page.getStaticPaths) throw new Error('pages/_error does not support getStaticProps, getServerSideProps or getStaticPaths. Use ErrorComponent.getInitialProps instead.');
+      return;
+    }
+    if (page.getServerSideProps && page.getStaticProps) throw new Error(`Page ${route.pattern} exports both getServerSideProps and getStaticProps. Choose one.`);
+    if (page.getStaticPaths && !page.getStaticProps) throw new Error(`Page ${route.pattern} exports getStaticPaths without getStaticProps.`);
+    if (page.getServerSideProps) { route.ssp = true; return; }
+    if (page.getStaticProps) route.ssg = true;
+    else if (route.gip || route.appGip) return;
+    if (isDynamic(route.pattern) && page.getStaticProps && !page.getStaticPaths) throw new Error(`Dynamic page ${route.pattern} with getStaticProps must export getStaticPaths.`);
+    if (!isDynamic(route.pattern) && page.getStaticPaths) throw new Error(`getStaticPaths is only valid on dynamic pages (${route.pattern}).`);
+    // Preserve data/export validation and SSG metadata. The dev PageCache calls
+    // getStaticPaths per request, including fallback:false and locale checks.
+    if (dev) return;
+    let entries = [{ path: route.pattern, params: {} }];
+    if (isDynamic(route.pattern)) {
+      if (!page.getStaticProps) return;
+      if (!staticListings.has(modulePath)) staticListings.set(modulePath, Promise.resolve().then(() => page.getStaticPaths(manifest.config.i18n ? {locales: manifest.config.i18n.locales, defaultLocale: manifest.config.i18n.defaultLocale} : {})));
+      const result = localizedStaticPaths(route, await staticListings.get(modulePath), manifest.config.i18n);
+      route.fallback = result.fallback;
+      entries = result.paths;
+    }
+    for (const entry of entries) {
+      if (paths.has(entry.path)) throw new Error(`Multiple pages prerender the same path: ${entry.path}.`);
+      paths.add(entry.path);
+      const rendered = await renderer.prerenderRoute({ ...manifest.config, manifest, distDir: stage, route, modulePath, path: entry.path, params: entry.params, client: route.client, css: route.css, pattern: route.pattern, errorStatus: route.errorStatus, buildId: manifest.buildId, production: !dev });
+      const file = `static/${createHash('sha256').update(entry.path).digest('hex').slice(0, 20)}.html`;
+      await writeFile(path.join(stage, file), rendered.body);
+      const seed = { routeId: route.id, path: entry.path, file, status: route.errorStatus || rendered.status || 200, headers: rendered.headers || {} };
+      if (route.ssg) {
+        seed.dataFile = file.replace(/\.html$/, '.json');
+        seed.revalidate = rendered.revalidate ?? false;
+        seed.generatedAt = rendered.generatedAt;
+        await writeFile(path.join(stage, seed.dataFile), rendered.dataJSON);
+      }
+      manifest.prerendered.push(seed);
+      if (!seedsByRoute.has(route.id)) seedsByRoute.set(route.id, []);
+      seedsByRoute.get(route.id).push(seed);
+    }
+    if (route.fallback === true) {
+      const rendered = await renderer.renderFallback({ ...manifest.config, modulePath, path: route.pattern, params: {}, client: route.client, css: route.css, pattern: route.pattern, buildId: manifest.buildId, production: !dev });
+      route.fallbackFile = `static/fallback-${route.id}.html`;
+      await writeFile(path.join(stage, route.fallbackFile), rendered.body);
+    }
+  }
+  // Error seeds must exist before ordinary pages can render notFound/failures.
+  for(const route of ordered.filter(route=>route.errorStatus))await renderRoute(route);
+  await mapConcurrent(ordered.filter(route=>!route.errorStatus),renderRoute);
+  // Rendering errors first must not change the published route/seed ordering.
+  manifest.prerendered = manifest.routes.flatMap(route => seedsByRoute.get(route.id) || []);
+}

package/build/prerender-worker.mjs

@@ -0,0 +1,10 @@
+import {prerenderPages} from './prerender-pages.mjs';
+import {prerenderApp} from './app-static.mjs';
+process.once('message',async({stage,manifest})=>{
+  try{
+    await prerenderPages(stage,manifest,false);
+    await prerenderApp(stage,manifest,false);
+    process.send({ok:true,manifest},()=>process.exit(0));
+  }catch(error){process.send({ok:false,error:error.stack||error.message},()=>process.exit(1));}
+});
+process.once('disconnect',()=>process.exit(1));

package/build/production-builder.mjs

@@ -0,0 +1,80 @@
+import {fork} from 'node:child_process';
+import {readFile,realpath} from 'node:fs/promises';
+import path from 'node:path';
+import {watchProject} from '../runtime/watch-project.mjs';
+import {createDevChangeFilter} from '../runtime/dev-file-changes.mjs';
+import {incrementalCompilerStats} from './incremental.mjs';
+
+/** Explicit reusable build session for integrations; always dispose it. */
+export async function createBuilder(projectRoot,options={}){
+  const root=await realpath(projectRoot);let disposed=false,pending=Promise.resolve();
+  return {
+    build(overrides={}){
+      if(disposed)return Promise.reject(new Error('Builder has been disposed'));
+      const task=pending.then(async()=>{const {build}=await import('./index.mjs');return build(root,{...options,...overrides,dev:false,incremental:true});});
+      pending=task.catch(()=>{});return task;
+    },
+    stats:incrementalCompilerStats,
+    async dispose(){disposed=true;await pending;const {disposeBuildSession}=await import('./index.mjs');await disposeBuildSession(root);},
+  };
+}
+
+// Application imports, SSG and RSC isolates belong to one build only. Keeping
+// esbuild's graph must not retain application globals or execute stale modules.
+export function isolatedPrerender(root,stage,manifest){
+  return new Promise((resolve,reject)=>{
+    const child=fork(new URL('./prerender-worker.mjs',import.meta.url),[],{cwd:root,execArgv:[],stdio:['ignore','inherit','inherit','ipc'],windowsHide:true});
+    let result;
+    const timeout=setTimeout(()=>{child.kill();reject(new Error('Production prerender exceeded ten minutes'));},600000);
+    child.once('error',error=>{clearTimeout(timeout);reject(error);});
+    child.on('message',value=>{result=value;});
+    child.once('exit',(code,signal)=>{clearTimeout(timeout);result?.ok&&code===0?resolve(result.manifest):reject(new Error(result?.error||`Prerender exited ${signal||code}`));});
+    child.send({stage,manifest});
+  });
+}
+
+/** Retain production graphs during local rebuilds; no HTTP listener/daemon. */
+export async function watchProduction(root,options={}){
+  let worker,watcher,stopping=false,timer,busy=false,queued=false;
+  const changed=new Set(),filter=createDevChangeFilter(root);
+  let output='.prnext';
+  const stopWorker=async()=>{
+    const old=worker;worker=undefined;if(!old||old.exitCode!==null||old.signalCode)return;
+    await new Promise(resolve=>{const timer=setTimeout(()=>old.kill(),5000);old.once('exit',()=>{clearTimeout(timer);resolve();});old.disconnect();});
+  };
+  const shutdown=async()=>{if(stopping)return;stopping=true;clearTimeout(timer);watcher?.close();await stopWorker();};
+  process.once('SIGINT',shutdown);process.once('SIGTERM',shutdown);
+  async function rebuild(){
+    if(stopping)return;if(busy){queued=true;return;}busy=true;
+    const pending=[...changed];changed.clear();
+    try{
+      const actual=await filter(pending);
+      if(worker&&!actual.length)return;
+      if(actual.some(file=>/(?:^|\/)(?:(?:next|prnext|contentlayer)\.config\.|package(?:-lock)?\.json$|pnpm-lock\.yaml$|yarn\.lock$|\.env)/.test(file)))await stopWorker();
+      if(!worker){worker=fork(new URL('./dev-worker.mjs',import.meta.url),[],{cwd:root,execArgv:[],stdio:['inherit','inherit','inherit','ipc'],windowsHide:true});}
+      const current=worker;
+      const result=await new Promise((resolve,reject)=>{
+        const cleanup=()=>{current.off('message',message);current.off('exit',exit);current.off('error',error);};
+        const message=value=>{if(value?.type==='result'){cleanup();resolve(value);}};
+        const exit=()=>{cleanup();reject(new Error('Production compiler exited'));};
+        const error=value=>{cleanup();reject(value);};
+        current.on('message',message);current.once('exit',exit);current.once('error',error);
+        current.send({type:'build',root,options:{...options,dev:false,incremental:true}});
+      });
+      if(result.recycle)await stopWorker();
+      if(!result.ok)throw new Error(result.error);
+      filter.acceptInputs(result.inputs||[]);
+      try{output=JSON.parse(await readFile(path.join(root,'.prnext-output.json'),'utf8')).distDir||output;}catch{}
+      await watcher?.refresh();
+      console.log(`Watching production sources (${result.compiler?.reused||0} compiler graph reuse(s)).`);
+    }catch(error){console.error(error.stack||error);}
+    finally{busy=false;if(queued&&!stopping){queued=false;void rebuild();}}
+  }
+  try{
+    watcher=await watchProject(root,{ignore:relative=>relative===output||relative.startsWith(output+'/'),onError:error=>{console.error(error);process.exitCode=1;void shutdown();},onChange:file=>{changed.add(String(file).replaceAll(path.sep,'/'));clearTimeout(timer);timer=setTimeout(()=>void rebuild(),150);}});
+    await rebuild();
+    // The watcher owns the event-loop lifetime. Stop signals close it and the
+    // compiler child; builds continue to publish through the existing lock.
+    await new Promise(resolve=>{const poll=setInterval(()=>{if(stopping&&!worker){clearInterval(poll);resolve();}},100);});
+  }finally{await shutdown();process.off('SIGINT',shutdown);process.off('SIGTERM',shutdown);}
+}

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-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' };
+}

package/build/styles.mjs

@@ -1,6 +1,8 @@
 import { build as bundle } from 'esbuild';
 import { access, readFile, readdir, writeFile, rm } from 'node:fs/promises';
 import { createRequire } from 'node:module';
+import {transform as transformCss, browserslistToTargets} from 'lightningcss';
+import browserslist from 'browserslist';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import path from 'node:path';
@@ -37,8 +39,18 @@ async function loadConfiguration(root) {
   return /\.(?:js|mjs|cjs)$/.test(filename) ? importConfiguration(filename) : JSON.parse(await readFile(filename, 'utf8'));
 }
 
-async function createProcessor(root) {
+async function createProcessor(root, engine) {
   const config = await loadConfiguration(root);
+  if (config === undefined && engine !== 'postcss') {
+    const targets=browserslistToTargets(browserslist(undefined,{path: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}});
+      // Preserve source origins for Sass URL rebasing and the ICSS extraction
+      // below. Custom PostCSS configurations always retain their own pipeline.
+      return postcss([]).process(result.code,{...options,map:result.map?{prev:JSON.parse(result.map.toString()),inline:false,annotation:false}:false});
+    }};
+  }
   if (config === undefined) return postcss([flexbugs(), presetEnv({ autoprefixer: { flexbox: 'no-2009' }, stage: 3, features: { 'custom-properties': false } })]);
   if (!config || typeof config !== 'object' || Array.isArray(config) || !config.plugins || typeof config.plugins !== 'object') throw new Error('PostCSS configuration must export an object with a plugins object or array; configuration functions are not supported.');
   const entries = Array.isArray(config.plugins)
@@ -122,7 +134,7 @@ function packageImporter(require) {
 }
 
 /** Build-only transformations, shared and deduplicated across all three React graphs. */
-export function createStyleProcessor({ projectRoot, sassOptions = {} }) {
+export function createStyleProcessor({ projectRoot, sassOptions = {}, cssEngine = 'auto' }) {
   const root = path.resolve(projectRoot);
   const require = createRequire(path.join(root, 'package.json'));
   const cache = new Map();
@@ -156,7 +168,7 @@ export function createStyleProcessor({ projectRoot, sassOptions = {} }) {
       sourceMap = compiled.sourceMap;
       for (const url of compiled.loadedUrls) if (url.protocol === 'file:') dependencies.add(fileURLToPath(url));
     }
-    processor ??= createProcessor(root);
+    processor ??= createProcessor(root,cssEngine);
     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-cache.mjs

@@ -1,23 +1,54 @@
 import { createHash } from 'node:crypto';
 import {sourceMapsEnabled} from './source-maps.mjs';
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {buildCacheIdentity,privateCacheDirectory,readCacheRecord,writeCacheRecord} from './persistent-cache.mjs';
 
 const entries = new Map();
 const byteLimit = 2 * 1024 * 1024, entryLimit = 256, itemLimit = 128 * 1024;
 let bytes = 0, hits = 0, misses = 0;
-export const transformCacheStats = () => ({entries:entries.size,bytes,hits,misses});
+let diskHits=0,diskWrites=0;
+const persistent=new AsyncLocalStorage();
+export const transformCacheStats = () => ({entries:entries.size,bytes,hits,misses,diskHits,diskWrites});
+export async function withPersistentTransforms(root,{enabled=true,dev=false}={},run){
+  if(!enabled||process.env.PRNEXT_BUILD_CACHE==='0')return run();
+  let directory,key,record;
+  try{directory=await privateCacheDirectory(root,dev?'transforms-dev-v1':'transforms-v1');key=directory&&await buildCacheIdentity(root);record=key&&await readCacheRecord(directory,key);}catch{return run();}
+  if(!directory||!key)return run();
+  const scope={key,values:new Map(),bytes:0,dirty:false};
+  for(const item of Array.isArray(record?.entries)?record.entries.slice(-4096):[]){
+    if(!Array.isArray(item)||item.length!==2||!/^[a-f0-9]{64}$/.test(item[0])||typeof item[1]!=='string')continue;
+    const size=Buffer.byteLength(item[1]);if(size>128*1024||scope.bytes+size>8*1024*1024)continue;
+    scope.values.set(item[0],item[1]);scope.bytes+=size;
+  }
+  const result=await persistent.run(scope,run);
+  if(scope.dirty&&await writeCacheRecord(directory,key,{entries:[...scope.values]}))diskWrites++;
+  return result;
+}
+function identity(kind,source,settings){return createHash('sha256').update(persistent.getStore()?.key||'memory').update(JSON.stringify([kind,settings,sourceMapsEnabled()])).update('\0').update(source).digest('hex');}
+function diskValue(key){const scope=persistent.getStore();if(!scope?.values.has(key))return;const value=scope.values.get(key);scope.values.delete(key);scope.values.set(key,value);diskHits++;hits++;return value;}
+function remember(key,output){
+  const scope=persistent.getStore();if(!scope||typeof output!=='string')return;
+  const size=Buffer.byteLength(output);if(size>128*1024)return;
+  const previous=scope.values.get(key);if(previous!==undefined){scope.bytes-=Buffer.byteLength(previous);scope.values.delete(key);}
+  while(scope.values.size&&(scope.values.size>=4096||scope.bytes+size>8*1024*1024)){const [old,value]=scope.values.entries().next().value;scope.values.delete(old);scope.bytes-=Buffer.byteLength(value);}
+  scope.values.set(key,output);scope.bytes+=size;scope.dirty=true;
+}
 
 // Only pure string transformations belong here. No AST, input source, plugin
 // closure or mutable build metadata survives in the cache. Include all options
 // affecting output in settings, including build identity and target mode.
 export function cachedTransform(kind, source, settings, transform) {
-  const key = createHash('sha256').update(JSON.stringify([kind,settings,sourceMapsEnabled()])).update('\0').update(source).digest('hex');
+  const key = identity(kind,source,settings);
   const found = entries.get(key);
   if (found) {
     hits++; entries.delete(key); entries.set(key,found);
+    if(persistent.getStore()&&!persistent.getStore().values.has(key))remember(key,found.output);
     return found.output;
   }
+  const saved=diskValue(key);if(saved!==undefined)return saved;
   misses++;
   const output = transform();
+  remember(key,output);
   // UTF-16 is an upper bound for the retained string payload. Metadata adds
   // engine overhead; the entry count also bounds that overhead.
   const size = output.length * 2 + key.length * 2;
@@ -33,11 +64,13 @@ export function cachedTransform(kind, source, settings, transform) {
 
 /** Async transforms share the same payload and entry budget as synchronous ones. */
 export async function cachedAsyncTransform(kind, source, settings, transform) {
-  const key = createHash('sha256').update(JSON.stringify([kind,settings,sourceMapsEnabled()])).update('\0').update(source).digest('hex');
+  const key = identity(kind,source,settings);
   const found = entries.get(key);
-  if (found) { hits++; entries.delete(key); entries.set(key,found); return found.output; }
+  if (found) { hits++; entries.delete(key); entries.set(key,found); if(persistent.getStore()&&!persistent.getStore().values.has(key))remember(key,found.output);return found.output; }
+  const saved=diskValue(key);if(saved!==undefined)return saved;
   misses++;
   const output = await transform();
+  remember(key,output);
   const size = output.length * 2 + key.length * 2;
   if (size <= itemLimit) {
     if (entries.has(key)) {bytes -= entries.get(key).size;entries.delete(key);}

package/build/type-command.mjs

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { loadProjectConfig } from './config.mjs';
+import { scanProject } from './scan.mjs';
+import { writeTypedRoutes } from './typed-routes.mjs';
+import { checkTypeScript, projectTsconfig } from './typescript.mjs';
+import { snapshotEnvConfig } from '../runtime/env.mjs';
+
+/** Generate/check from route discovery only; no bundler, native server or install. */
+export async function runTypeCommand(directory, { check = false } = {}) {
+  const root = path.resolve(directory);
+  const report = { version: 1, root, command: check ? 'typecheck' : 'typegen', ok: false, typedRoutes: false,
+    tsconfig: null, routes: 0, updated: [], configUpdates: [], notes: [], errors: [] };
+  const restore = snapshotEnvConfig();
+  try {
+    const config = await loadProjectConfig(root);
+    const tsconfig = await projectTsconfig(root, config);
+    if (!tsconfig) throw new Error('Type commands require an existing tsconfig.json, or typescript.tsconfigPath pointing to an existing configuration.');
+    const resolve = createRequire(path.join(root, 'package.json'));
+    try { resolve.resolve('typescript'); }
+    catch { throw new Error('Install typescript as a dev dependency in the application before running typegen or typecheck.'); }
+    report.tsconfig = path.relative(root, tsconfig).replaceAll(path.sep, '/');
+    // Explicit type commands opt into route generation unless the application
+    // explicitly disables it. A clean checkout gets fresh declarations first.
+    report.typedRoutes = config.typedRoutes !== false;
+    const project = await scanProject(root, { basePath: config.basePath, pageExtensions: config.pageExtensions, i18n: config.i18n });
+    report.routes = project.routes.filter(route => route.kind === 'page' && !route.internal && !route.errorStatus).length;
+    const updates = await writeTypedRoutes(root, project, { ...config, typedRoutes: report.typedRoutes });
+    report.updated = (updates || []).map(file => path.relative(root, file).replaceAll(path.sep, '/')).sort();
+    report.configUpdates = report.updated.filter(file => file === report.tsconfig || file === 'prnext-env.d.ts');
+    if (report.configUpdates.length) report.notes.push('Updated the selected tsconfig roots/Next type aliases and/or prnext-env.d.ts to include generated declarations. Existing JSONC comments and inherited settings are preserved.');
+    if (!report.typedRoutes) report.notes.push('Route declarations are disabled by typedRoutes: false; application TypeScript is still checked by typecheck.');
+    if (check) {
+      await checkTypeScript(root, config, { tsconfig, force: true });
+      if (config.typescript?.ignoreBuildErrors) report.notes.push('typecheck checks errors even when typescript.ignoreBuildErrors is enabled for builds.');
+    }
+    report.ok = true;
+  } catch (error) { report.errors.push(error.message); }
+  finally { restore(); }
+  return report;
+}

package/build/typed-routes.mjs

@@ -0,0 +1,91 @@
+import {readFile,writeFile,mkdir,rename,lstat} from 'node:fs/promises';
+import {createRequire} from 'node:module';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const marker='// Generated by PRNext: typed route registry. Do not edit.';
+async function changed(file,contents,updates){
+  const info=await lstat(file).catch(error=>{if(error.code!=='ENOENT')throw error;});
+  if(info&&(!info.isFile()||info.isSymbolicLink()))throw Error('Typed routes cannot replace a non-regular file: '+file);
+  if(await readFile(file,'utf8').catch(()=>null)===contents)return;
+  const temporary=file+'.'+randomUUID()+'.tmp';try{await writeFile(temporary,contents,{mode:0o600,flag:'wx'});await rename(temporary,file);updates?.add(file);}finally{const {rm}=await import('node:fs/promises');await rm(temporary,{force:true});}
+}
+export function routeDeclarations(project,{enabled=true}={}){
+  const patterns=[...new Set(project.routes.filter(route=>route.kind==='page'&&!route.internal&&!route.errorStatus).map(route=>route.pattern))].sort();
+  if(patterns.length>10000)throw Error('Typed routes supports at most 10,000 page patterns');
+  const fields=patterns.map(pattern=>{
+    const segments=pattern.split('/');if(segments.length>33)throw Error('Typed routes supports at most 32 route segments');
+    const params=segments.flatMap(part=>{
+      const optional=/^\[\[\.\.\.([^\]]+)\]\]$/.exec(part),rest=/^\[\.\.\.([^\]]+)\]$/.exec(part),single=/^\[([^\]]+)\]$/.exec(part);
+      const match=optional||rest||single;return match?[`${JSON.stringify(match[1])}${optional?'?':''}: ${single?'string':'string[]'}`]:[];
+    });
+    return `    ${JSON.stringify(pattern)}: {${params.join('; ')}};`;
+  });
+  return marker+'\nexport {};\ndeclare global {\n  namespace PRNext {\n'+(enabled?'    interface RouteConfig { enabled: true }\n':'')+'    interface RouteMap {\n'+fields.join('\n')+'\n    }\n  }\n}\n';
+}
+// Bind missing Next-style imports to the matching PRNext declarations. Existing
+// aliases remain authoritative; inherited aliases retain their resolved targets.
+async function bindTypes(filename,ts,updates){
+  const source=await readFile(filename,'utf8');
+  const parsed=ts.getParsedCommandLineOfConfigFile(filename,{},{...ts.sys,onUnRecoverableConfigFileDiagnostic:()=>{}});
+  const paths=parsed.options.paths||{},missing=['next','next/*'].filter(name=>!Object.hasOwn(paths,name));if(!missing.length)return;
+  const ast=ts.parseJsonText(filename,source),object=ast.statements[0].expression;
+  const options=object.properties.find(p=>p.name?.text==='compilerOptions')?.initializer;
+  const ownPaths=options?.properties?.find(p=>p.name?.text==='paths')?.initializer;
+  const base=parsed.options.baseUrl||path.dirname(filename),oldBase=parsed.options.baseUrl||parsed.options.pathsBasePath||path.dirname(filename);
+  const relative=file=>{let value=path.relative(base,file).replaceAll(path.sep,'/');return value.startsWith('.')?value:'./'+value;};
+  const compat=fileURLToPath(new URL('../compat/',import.meta.url));
+  const additions=Object.fromEntries(missing.map(name=>[name,[relative(path.join(compat,name==='next'?'index.d.ts':'*.d.cts'))]]));
+  let target,values;
+  if(ownPaths){if(!ts.isObjectLiteralExpression(ownPaths))throw Error('tsconfig.compilerOptions.paths must be an object');target=ownPaths;values=additions;}
+  else{
+    const merged={...Object.fromEntries(Object.entries(paths).map(([name,values])=>[name,values.map(value=>relative(path.resolve(oldBase,value)))])),...additions};
+    if(options){if(!ts.isObjectLiteralExpression(options))throw Error('tsconfig.compilerOptions must be an object');target=options;values={paths:merged};}
+    else{target=object;values={compilerOptions:{paths:merged}};}
+  }
+  const position=target.end-1,separator=target.properties.length&&!target.properties.hasTrailingComma?',':'';
+  const text=Object.entries(values).map(([name,value])=>JSON.stringify(name)+': '+JSON.stringify(value)).join(',\n  ');
+  await changed(filename,source.slice(0,position)+separator+'\n  '+text+'\n'+source.slice(position),updates);
+}
+/** Include one generated root without replacing JSONC comments or inherited include globs. */
+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;
+  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');
+  if(parsed.fileNames.some(name=>path.resolve(name)===helper)){await bindTypes(filename,ts,updates);return;}
+  const ast=ts.parseJsonText(filename,source),object=ast.statements[0]?.expression;
+  if(!object||!ts.isObjectLiteralExpression(object))throw Error('Cannot add typed route declarations to tsconfig');
+  const property=object.properties.find(p=>p.name?.text==='files');
+  let edited;
+  if(property){
+    if(!ts.isArrayLiteralExpression(property.initializer))throw Error('tsconfig.files must be an array');
+    const array=property.initializer,position=array.end-1,separator=array.elements.length&&!array.elements.hasTrailingComma?',':'';
+    edited=source.slice(0,position)+separator+JSON.stringify(path.relative(path.dirname(filename),helper).replaceAll(path.sep,'/'))+source.slice(position);
+  }else{
+    // TS resolves inherited files relative to this config in parsed.raw.files.
+    const files=[...(parsed.raw.files||[]),path.relative(path.dirname(filename),helper).replaceAll(path.sep,'/')];
+    const position=object.end-1,separator=object.properties.length&&!object.properties.hasTrailingComma?',':'';
+    edited=source.slice(0,position)+separator+'\n  "files": '+JSON.stringify(files)+'\n'+source.slice(position);
+  }
+  await changed(filename,edited,updates);
+  await bindTypes(filename,ts,updates);
+}
+export async function writeTypedRoutes(root,project,config){
+  const updates=new Set();
+  const directory=path.join(root,'.prnext-types'),file=path.join(directory,'routes.d.ts');
+  const info=await lstat(directory).catch(error=>{if(error.code!=='ENOENT')throw error;});
+  if(info&&(!info.isDirectory()||info.isSymbolicLink())){if(config.typedRoutes)throw Error('.prnext-types must be a real directory');return;}
+  if(!config.typedRoutes){const existing=await readFile(file,'utf8').catch(()=>null);if(existing?.startsWith(marker))await changed(file,routeDeclarations({routes:[]},{enabled:false}),updates);return [...updates];}
+  await mkdir(directory,{recursive:true,mode:0o700});
+  const previous=await readFile(file,'utf8').catch(error=>{if(error.code!=='ENOENT')throw error;});
+  if(previous&&!previous.startsWith(marker))throw Error('Refusing to overwrite a non-generated route registry');
+  await changed(file,routeDeclarations(project),updates);
+  const helper=path.join(root,'prnext-env.d.ts'),reference='/// <reference path="./.prnext-types/routes.d.ts" />';
+  const contents=await readFile(helper,'utf8').catch(error=>{if(error.code==='ENOENT')return '';throw error;});
+  if(!contents.includes(reference))await changed(helper,reference+'\n'+contents,updates);
+  await includeTypes(root,config,helper,updates);
+  return [...updates];
+}