@thomas.f/prnext 0.1.0-alpha.1

package/build/css-modules.mjs

@@ -0,0 +1,114 @@
+import { build as bundle } from 'esbuild';
+import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { runInNewContext } from 'node:vm';
+import { createRequire } from 'node:module';
+import { createStyleProcessor, stylesheetPattern, moduleStylesheetPattern } from './styles.mjs';
+
+const assetLoaders = Object.fromEntries(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'].map(ext => [ext, 'file']));
+
+async function resolveCss(esbuild, args) {
+  const result = await esbuild.resolve(args.path, { resolveDir: args.resolveDir, kind: args.kind, pluginData: { prnextResolvingCss: true } });
+  if (result.errors.length) return result;
+  // Server packages are normally external, but a direct CSS import still needs compilation.
+  if (result.external) {
+    try { return { path: await realpath(createRequire(path.join(args.resolveDir, '__prnext_resolve.cjs')).resolve(args.path)) }; }
+    catch (error) { return { errors: [{ text: error.message }] }; }
+  }
+  return { path: await realpath(result.path) };
+}
+
+/** One cached CSS compilation supplies identical class maps to the server and the browser. */
+export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions }) {
+  const cache = new Map();
+  const processor = createStyleProcessor({ projectRoot, sassOptions });
+  const hash = file => createHash('sha256').update(path.relative(projectRoot, file).replaceAll(path.sep, '/')).digest('hex').slice(0, 12);
+
+  async function compile(file) {
+    const result = await bundle({
+      absWorkingDir: projectRoot,
+      stdin: { contents: `import styles from ${JSON.stringify(file)}; export default styles;`, resolveDir: projectRoot, loader: 'js' },
+      outfile: path.join(stage, '.cssmodules', hash(file) + '.js'),
+      bundle: true,
+      write: false,
+      format: 'cjs',
+      platform: 'browser',
+      logLevel: 'silent',
+      loader: assetLoaders,
+      publicPath: assetBase,
+      assetNames: '[name]-[hash]',
+      // Preserve these identifiers; the final browser build may minify its JS freely.
+      minifyIdentifiers: false,
+      plugins: [{
+        name: 'prnext-deterministic-css-identifiers',
+        setup(esbuild) {
+          esbuild.onResolve({ filter: moduleStylesheetPattern }, async args => {
+            if (args.pluginData?.prnextResolvingCss || args.path.startsWith('prnext-css:')) return;
+            const resolved = await resolveCss(esbuild, args);
+            if (resolved.errors) return { errors: resolved.errors };
+            const basename = path.basename(resolved.path).replace(/\.module\.(?:css|scss|sass)$/i, '').replace(/[^\w-]/g, '_');
+            return { path: `r${hash(resolved.path)}_${basename}.module.css`, namespace: 'prnext-local-css', pluginData: { source: resolved.path } };
+          });
+          esbuild.onLoad({ filter: /.*/, namespace: 'prnext-local-css' }, async args => {
+            const transformed = await processor.process(args.pluginData.source);
+            return { contents: transformed.css, loader: 'local-css', resolveDir: path.dirname(args.pluginData.source), watchFiles: transformed.watchFiles };
+          });
+          esbuild.onLoad({ filter: stylesheetPattern, namespace: 'file' }, async args => {
+            const transformed = await processor.process(args.path);
+            return { contents: transformed.css, loader: 'css', resolveDir: path.dirname(args.path), watchFiles: transformed.watchFiles };
+          });
+          esbuild.onResolve({ filter: /^\// }, args => args.kind === 'url-token' ? { path: args.path, external: true } : undefined);
+        },
+      }],
+    });
+    const javascript = result.outputFiles.find(output => output.path.endsWith('.js'));
+    const stylesheet = result.outputFiles.find(output => output.path.endsWith('.css'));
+    if (!javascript || !stylesheet) throw new Error(`Unable to compile CSS Module ${file}.`);
+    // This is esbuild's generated export map, whose only inputs are CSS files.
+    // The isolated context deliberately has no require, process, network, or filesystem.
+    const module = { exports: {} };
+    runInNewContext(javascript.text, { module }, { timeout: 1000, filename: 'prnext-css-exports.cjs' });
+    const mapping = JSON.stringify({ ...module.exports.default, ...(await processor.process(file)).exports });
+    await mkdir(path.join(stage, 'assets'), { recursive: true });
+    for (const output of result.outputFiles) {
+      if (output === javascript || output === stylesheet) continue;
+      await writeFile(path.join(stage, 'assets', path.basename(output.path)), output.contents);
+    }
+    return { mapping, css: stylesheet.text };
+  }
+
+  function get(file) {
+    if (!cache.has(file)) cache.set(file, compile(file));
+    return cache.get(file);
+  }
+
+  return {
+    plugin(browser, { emitStyles = () => true } = {}) {
+      return {
+        name: 'prnext-shared-css-modules',
+        setup(esbuild) {
+          esbuild.onResolve({ filter: moduleStylesheetPattern }, async args => {
+            if (args.pluginData?.prnextResolvingCss || args.path.startsWith('prnext-css:')) return;
+            const resolved = await resolveCss(esbuild, args);
+            if (resolved.errors) return { errors: resolved.errors };
+            return { path: resolved.path, namespace: 'prnext-css-mapping' };
+          });
+          esbuild.onLoad({ filter: /.*/, namespace: 'prnext-css-mapping' }, async args => {
+            const compiled = await get(args.path);
+            return { contents: `${browser && emitStyles(args.path) ? `import ${JSON.stringify('prnext-css:' + args.path)};` : ''} export default ${compiled.mapping};`, loader: 'js' };
+          });
+          if (browser) {
+            esbuild.onLoad({ filter: stylesheetPattern, namespace: 'file' }, async args => {
+              const transformed = await processor.process(args.path);
+              return { contents: transformed.css, loader: 'css', resolveDir: path.dirname(args.path), watchFiles: transformed.watchFiles };
+            });
+            esbuild.onResolve({ filter: /^prnext-css:/ }, args => ({ path: args.path.slice('prnext-css:'.length), namespace: 'prnext-compiled-css' }));
+            esbuild.onLoad({ filter: /.*/, namespace: 'prnext-compiled-css' }, async args => ({ contents: (await get(args.path)).css, loader: 'css', resolveDir: path.dirname(args.path) }));
+            esbuild.onResolve({ filter: /^\// }, args => args.kind === 'url-token' ? { path: args.path, external: true } : undefined);
+          }
+        },
+      };
+    },
+  };
+}

package/build/custom-routes.mjs

@@ -0,0 +1,363 @@
+import { parse, tokensToRegexp } from 'path-to-regexp';
+import { withLocale } from '../compat/locale.cjs';
+
+const MAX_ROUTES = 1000;
+const MAX_STRING = 4096;
+const MAX_CONDITIONS = 16;
+const MAX_PARAMS = 64;
+const MAX_HEADERS = 64;
+const MAX_MANIFEST_BYTES = 2 * 1024 * 1024;
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const STATUS = new Set([301, 302, 303, 307, 308]);
+
+function fail(where, message) { throw new Error(`Invalid custom route ${where}: ${message}`); }
+function record(value, where) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail(where, 'expected an object');
+}
+function keys(value, allowed, where) {
+  const unknown = Object.keys(value).filter(key => !allowed.includes(key));
+  if (unknown.length) fail(where, `unsupported fields: ${unknown.join(', ')}`);
+}
+function string(value, where, { empty = false, max = MAX_STRING, header = false } = {}) {
+  if (typeof value !== 'string' || (!empty && !value.length) || Buffer.byteLength(value) > max) {
+    fail(where, `expected ${empty ? 'a' : 'a nonempty'} string of at most ${max} bytes`);
+  }
+  if ((header ? /[\u0000-\u0008\u000a-\u001f\u007f]/ : CONTROL).test(value)) fail(where, 'control characters are forbidden');
+  return value;
+}
+function parseTokens(value, where, delimiter = '/') {
+  try { return parse(value, { delimiter }); }
+  catch (error) { fail(where, `invalid path pattern (${error.message})`); }
+}
+function addParam(params, name, where, info = {}) {
+  if (params.has(name)) fail(where, `duplicate parameter ${JSON.stringify(name)}`);
+  if (params.size >= MAX_PARAMS) fail(where, `at most ${MAX_PARAMS} parameters are supported`);
+  params.set(name, info);
+}
+
+// Keep these checks aligned with custom_routes.rs::js_regex. JavaScript accepts
+// identity escapes which have different meanings in Rust, and the native
+// matcher deliberately limits insensitive character classes to ASCII rather
+// than silently applying Rust's broader Unicode case folding.
+function validateNativeRegex(pattern, insensitive, where) {
+  let inClass = false;
+  let classText = '';
+  const escapedLetters = new Set('dDwWsSbBnrtvfxuk');
+  for (let index = 0; index < pattern.length; index++) {
+    let value = pattern[index];
+    if (value === '\\') {
+      const kind = pattern[++index];
+      if (kind === undefined) fail(where, 'trailing regular-expression escape');
+      if (/[A-Za-z]/.test(kind) && !escapedLetters.has(kind)) {
+        fail(where, `unsupported ECMAScript escape \\${kind} in the native custom-route matcher`);
+      }
+      if (kind === 'x' || kind === 'u') {
+        const length = kind === 'x' ? 2 : 4;
+        const digits = pattern.slice(index + 1, index + length + 1);
+        if (digits.length !== length || !/^[0-9A-Fa-f]+$/.test(digits)) fail(where, 'unsupported ECMAScript hex/Unicode escape; use \\xHH or \\uHHHH');
+        const code = Number.parseInt(digits, 16);
+        if (code >= 0xd800 && code <= 0xdfff) fail(where, 'UTF-16 surrogate regex escapes are unsupported by the native matcher');
+        value = String.fromCharCode(code);
+        index += length;
+      } else value = `\\${kind}`;
+      if (inClass) classText += value;
+      continue;
+    }
+    if (!inClass && value === '[') { inClass = true; classText = ''; }
+    else if (inClass && value === ']') {
+      if (insensitive && (/[^\x00-\x7f]/.test(classText) || classText.includes('\\u'))) {
+        fail(where, 'case-insensitive Unicode character classes are unsupported; use Unicode literals or a case-sensitive has/missing condition');
+      }
+      inClass = false;
+    } else if (inClass) classText += value;
+  }
+}
+
+function compileSource(source, params, where) {
+  string(source, `${where}.source`);
+  if (!source.startsWith('/') || source.startsWith('//')) fail(where, 'source must start with a single /');
+  const tokens = parseTokens(source, `${where}.source`);
+  const captures = [];
+  let regex;
+  try {
+    regex = tokensToRegexp(tokens, captures, { strict: true, sensitive: false, delimiter: '/' }).source;
+  } catch (error) { fail(where, `invalid source (${error.message})`); }
+  // Match Next's optional final slash without allowing query/hash delimiters.
+  regex = regex.replace(/\$$/, '(?:/)?$').replace(/\\\//g, '/');
+  if (Buffer.byteLength(regex) > MAX_STRING) fail(where, 'compiled source exceeds 4096 bytes');
+  validateNativeRegex(regex, true, `${where}.source`);
+  const compiledKeys = captures.map(token => {
+    const repeat = token.modifier === '*' || token.modifier === '+';
+    const name = typeof token.name === 'number' ? null : token.name;
+    if (name !== null) addParam(params, name, where, { repeat, optional: token.modifier === '?' || token.modifier === '*' });
+    return { name, repeat, separator: `${token.prefix}${token.suffix}` };
+  });
+  if (captures.length > MAX_PARAMS) fail(where, `at most ${MAX_PARAMS} captures are supported`);
+  return { source, regex, keys: compiledKeys };
+}
+
+function regexCaptures(pattern, where) {
+  try { new RegExp(pattern); }
+  catch (error) { fail(where, `invalid condition regex (${error.message})`); }
+  const captures = [];
+  let count = 0;
+  let inClass = false;
+  for (let index = 0; index < pattern.length; index++) {
+    const char = pattern[index];
+    if (char === '\\') { index++; continue; }
+    if (char === '[') inClass = true;
+    else if (char === ']') inClass = false;
+    else if (char === '(' && !inClass) {
+      if (pattern[index + 1] !== '?') count++;
+      else if (pattern[index + 2] === '<' && !['=', '!'].includes(pattern[index + 3])) {
+        const end = pattern.indexOf('>', index + 3);
+        const name = pattern.slice(index + 3, end);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) fail(where, 'named captures must use ASCII identifier names');
+        captures.push({ name, index: ++count });
+      }
+    }
+  }
+  if (count > MAX_PARAMS) fail(where, `at most ${MAX_PARAMS} regex captures are supported`);
+  return captures;
+}
+
+function conditions(value, params, where, expose) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_CONDITIONS) fail(where, `expected at most ${MAX_CONDITIONS} conditions`);
+  const seen = new Set();
+  return value.map((item, index) => {
+    const location = `${where}[${index}]`;
+    record(item, location); keys(item, ['type', 'key', 'value'], location);
+    if (!['header', 'cookie', 'query', 'host'].includes(item.type)) fail(location, 'unknown condition type');
+    const result = { type: item.type, captures: [] };
+    if (item.type === 'host') {
+      if (item.key !== undefined) fail(location, 'host conditions do not accept key');
+      if (!item.value) fail(location, 'host conditions require a nonempty value');
+    } else {
+      string(item.key, `${location}.key`, { max: 256 });
+      if ((item.type === 'header' || item.type === 'cookie') && !HEADER_NAME.test(item.key)) fail(location, 'invalid header/cookie key');
+      result.key = item.type === 'header' ? item.key.toLowerCase() : item.key;
+    }
+    if (item.value !== undefined) {
+      string(item.value, `${location}.value`, { empty: true, max: 1024 });
+      if (item.value) {
+        // A noncapturing wrapper keeps alternations anchored as a whole.
+        result.regex = `^(?:${item.value})$`;
+        result.captures = regexCaptures(result.regex, location);
+        validateNativeRegex(result.regex, false, `${location}.value`);
+        if (item.type === 'host' && !result.captures.length) result.capture = 'host';
+      }
+    }
+    if (!result.regex && result.key) {
+      const name = result.key.replace(/[^A-Za-z]/g, '');
+      if (name) result.capture = name;
+    }
+    const identity = JSON.stringify(result);
+    if (seen.has(identity)) fail(where, 'duplicate condition');
+    seen.add(identity);
+    if (expose) {
+      for (const capture of result.captures) addParam(params, capture.name, location);
+      if (result.capture) addParam(params, result.capture, location);
+    }
+    return result;
+  });
+}
+
+function template(value, params, where, { path = false, delimiter = '/', strict = false } = {}) {
+  const tokens = path ? parseTokens(value, where, delimiter) : nonPathTokens(value, params, strict, where);
+  return tokens.map(token => {
+    if (typeof token === 'string') return token;
+    if (typeof token.name === 'number' || !params.has(token.name)) fail(where, `unknown destination parameter ${JSON.stringify(token.name)}`);
+    if (params.get(token.name).repeat && !['*', '+'].includes(token.modifier)) {
+      fail(where, `repeated parameter :${token.name} requires * or + in the destination`);
+    }
+    return { param: token.name, prefix: token.prefix, suffix: token.suffix, modifier: token.modifier,
+      ...(token.join !== undefined ? { join: token.join } : {}) };
+  });
+}
+
+function nonPathTokens(value, params, strict, where) {
+  const result = [];
+  let text = '';
+  const flush = () => { if (text) result.push(text); text = ''; };
+  for (let index = 0; index < value.length;) {
+    if (value[index] === '\\' && value[index + 1] === ':') { text += ':'; index += 2; continue; }
+    const match = value[index] === ':' && /^:([A-Za-z0-9_]+)([?*+]?)/.exec(value.slice(index));
+    if (!match) { text += value[index++]; continue; }
+    if (!params.has(match[1])) {
+      // Non-path strings routinely contain literal colons (CSP, URLs, times).
+      // Reject unresolved parameter-like query placeholders, but retain URI
+      // schemes and numeric ports rather than guessing they are parameters.
+      if (strict && /^[A-Za-z_]/.test(match[1])) fail(where, `unknown destination parameter ${JSON.stringify(match[1])}`);
+      text += match[0]; index += match[0].length; continue;
+    }
+    flush();
+    // Next compiles non-path values with an artificial leading slash, then
+    // removes it. Arrays at the beginning consequently join with '/', whereas
+    // embedded arrays use the preceding path-to-regexp prefix ('.' or '/').
+    const join = index === 0 || value[index - 1] === '/' ? '/' : value[index - 1] === '.' ? '.' : '';
+    result.push({ name: match[1], prefix: '', suffix: '', modifier: match[2],
+      ...(['*', '+'].includes(match[2]) ? { join } : {}) });
+    index += match[0].length;
+  }
+  flush(); return result;
+}
+
+function splitDestination(value, where) {
+  let rest = value;
+  const hashIndex = rest.indexOf('#');
+  const hash = hashIndex === -1 ? '' : rest.slice(hashIndex + 1);
+  if (hashIndex !== -1) rest = rest.slice(0, hashIndex);
+  const queryIndex = rest.indexOf('?');
+  const search = queryIndex === -1 ? '' : rest.slice(queryIndex + 1);
+  if (queryIndex !== -1) rest = rest.slice(0, queryIndex);
+  let protocol, hostname, port;
+  const external = /^https?:\/\//i.test(rest);
+  if (external) {
+    const match = /^(https?):\/\/([^/]+)(\/.*)?$/i.exec(rest);
+    if (!match) fail(where, 'invalid external destination');
+    protocol = match[1].toLowerCase();
+    let authority = match[2];
+    if (authority.includes('@') || authority.includes('\\')) fail(where, 'external credentials and backslashes are unsupported');
+    if (authority.startsWith('[')) {
+      const ipv6 = /^(\[[0-9a-fA-F:.]+\])(?::(\d+))?$/.exec(authority);
+      if (!ipv6) fail(where, 'invalid IPv6 destination');
+      hostname = ipv6[1]; port = ipv6[2];
+    } else {
+      const numericPort = /:(\d+)$/.exec(authority);
+      if (numericPort) { port = numericPort[1]; authority = authority.slice(0, -numericPort[0].length); }
+      hostname = authority;
+      if (!hostname || /[\s%]/.test(hostname)) fail(where, 'invalid external hostname');
+    }
+    if (port && (+port > 65535 || +port === 0)) fail(where, 'invalid destination port');
+    rest = match[3] || '/';
+  } else if (!rest.startsWith('/') || rest.startsWith('//')) {
+    fail(where, 'destination must start with /, http:// or https://');
+  }
+  if (rest.includes('\\') && /\\(?![:*+?(){}\\])/.test(rest)) fail(where, 'invalid destination escape');
+  return { external, protocol, hostname, port, pathname: rest, search, hash };
+}
+
+function destination(value, params, where, rewrite) {
+  string(value, where);
+  const pieces = splitDestination(value, where);
+  const pathname = template(pieces.pathname, params, `${where}.pathname`, { path: true });
+  const hash = template(pieces.hash, params, `${where}.hash`, { path: true });
+  const result = { external: pieces.external, pathname, query: [], hash };
+  if (pieces.external) {
+    result.protocol = pieces.protocol;
+    result.hostname = pieces.hostname.startsWith('[') ? [pieces.hostname] : template(pieces.hostname, params, `${where}.hostname`, { path: true, delimiter: '.' });
+    if (pieces.port) result.port = pieces.port;
+  }
+  const query = new URLSearchParams(pieces.search);
+  if ([...query].length > 128) fail(where, 'at most 128 destination query entries are supported');
+  for (const [key, value] of query) {
+    string(key, `${where}.query key`, { empty: true }); string(value, `${where}.query value`, { empty: true });
+    result.query.push({ key, value: template(value, params, `${where}.query`, { strict: true }) });
+  }
+  result.appendParamsToQuery = rewrite && ![...pathname, ...hash, ...(result.hostname || [])].some(token => typeof token !== 'string');
+  return result;
+}
+
+function matcher(route, params, where, expose = true) {
+  const result = compileSource(route.source, params, where);
+  result.has = conditions(route.has, params, `${where}.has`, expose);
+  result.missing = conditions(route.missing, params, `${where}.missing`, false);
+  const existing = new Set(result.has.map(item => JSON.stringify(item)));
+  if (result.missing.some(item => existing.has(JSON.stringify(item)))) fail(where, 'the same condition cannot be required and missing');
+  return result;
+}
+
+// A deployment pathname is literal, not additional path-to-regexp syntax.
+function mountedPattern(source, basePath) {
+  if (!basePath) return source;
+  const prefix = basePath.replace(/[\\:*+?(){}[\]]/g, '\\$&');
+  return prefix + (source === '/' ? '' : source);
+}
+
+/** Middleware only needs a predicate; its captures are not destination params. */
+export function compileRouteMatcher(input, where = 'middleware.matcher', { basePath = '' } = {}) {
+  const route = typeof input === 'string' ? { source: input } : input;
+  record(route, where);
+  keys(route, ['source', 'has', 'missing', 'locale'], where);
+  if (route.locale !== undefined && route.locale !== false) fail(where, 'locale only accepts false while that feature is unsupported');
+  // Validate the original source before adding a mount prefix, otherwise an
+  // invalid relative source could accidentally become an absolute pattern.
+  string(route.source, `${where}.source`);
+  if (!route.source.startsWith('/') || route.source.startsWith('//')) fail(where, 'source must start with a single /');
+  return matcher({ ...route, source: mountedPattern(route.source, basePath) }, new Map(), where, false);
+}
+
+function compileRoute(route, type, where, basePath = '') {
+  record(route, where);
+  keys(route, ['source', 'has', 'missing', 'basePath', 'locale', ...(type === 'header' ? ['headers'] : type === 'redirect' ? ['destination', 'permanent', 'statusCode'] : ['destination'])], where);
+  for (const option of ['basePath', 'locale']) if (route[option] !== undefined && route[option] !== false) fail(where, `${option} only accepts false`);
+  string(route.source, `${where}.source`);
+  if (!route.source.startsWith('/') || route.source.startsWith('//')) fail(where, 'source must start with a single /');
+  if (type === 'rewrite' && route.basePath === false && !/^https?:\/\//i.test(route.destination)) fail(where, 'basePath:false rewrites require an external HTTP(S) destination');
+  if (basePath && route.basePath !== false) {
+    route = { ...route, source: mountedPattern(route.source, basePath),
+      ...(typeof route.destination === 'string' && route.destination.startsWith('/') && !route.destination.startsWith('//')
+        ? { destination: mountedPattern(route.destination, basePath) } : {}) };
+  }
+  const params = new Map();
+  const result = matcher(route, params, where);
+  if (type === 'header') {
+    if (!Array.isArray(route.headers) || !route.headers.length || route.headers.length > MAX_HEADERS) fail(where, `headers must contain 1–${MAX_HEADERS} entries`);
+    result.headers = route.headers.map((header, index) => {
+      const location = `${where}.headers[${index}]`;
+      record(header, location); keys(header, ['key', 'value'], location);
+      string(header.key, `${location}.key`, { max: 256 });
+      string(header.value, `${location}.value`, { empty: true, header: true });
+      const key = template(header.key, params, `${location}.key`);
+      if (!HEADER_NAME.test(key.map(token => typeof token === 'string' ? token : 'param').join(''))) fail(location, 'invalid header name');
+      return { key, value: template(header.value, params, `${location}.value`) };
+    });
+    // Duplicate response header names intentionally retain source order: the
+    // later matching header wins, just as Next custom headers do.
+  } else {
+    result.destination = destination(route.destination, params, `${where}.destination`, type === 'rewrite');
+    if (type === 'redirect') {
+      if (route.permanent !== undefined && route.statusCode !== undefined) fail(where, 'permanent and statusCode are mutually exclusive');
+      if (route.statusCode !== undefined) {
+        if (!STATUS.has(route.statusCode)) fail(where, 'statusCode must be 301, 302, 303, 307 or 308');
+        result.statusCode = route.statusCode;
+      } else {
+        if (typeof route.permanent !== 'boolean') fail(where, 'redirect requires permanent or statusCode');
+        result.statusCode = route.permanent ? 308 : 307;
+      }
+    }
+  }
+  return result;
+}
+
+/** Compile Next custom route callbacks into the bounded native manifest. */
+export async function compileCustomRoutes(config = {}) {
+  const loaded = await Promise.all(['headers', 'redirects', 'rewrites'].map(async name => {
+    if (config[name] === undefined) return [];
+    if (typeof config[name] !== 'function') fail(name, 'configuration must be a function');
+    return await config[name]();
+  }));
+  let total = 0;
+  const compileList = (value, type, where) => {
+    if (!Array.isArray(value)) fail(where, 'callback must return an array');
+    if (config.i18n) value = value.flatMap(route => route?.locale === false ? [route] : [...config.i18n.locales.filter(locale => locale !== config.i18n.defaultLocale), config.i18n.defaultLocale].map(locale => ({
+      ...route, source: withLocale(route.source, locale, config.i18n.defaultLocale),
+      ...(typeof route.destination === 'string' && route.destination.startsWith('/') && !route.destination.startsWith('//') ? {destination:withLocale(route.destination,locale,config.i18n.defaultLocale)} : {}),
+    })));
+    total += value.length;
+    if (total > MAX_ROUTES) fail(where, `at most ${MAX_ROUTES} custom routes are supported`);
+    return value.map((route, index) => compileRoute(route, type, `${where}[${index}]`, config.basePath || ''));
+  };
+  const headers = compileList(loaded[0], 'header', 'headers');
+  const redirects = compileList(loaded[1], 'redirect', 'redirects');
+  let rawRewrites = loaded[2];
+  if (Array.isArray(rawRewrites)) rawRewrites = { afterFiles: rawRewrites };
+  record(rawRewrites, 'rewrites'); keys(rawRewrites, ['beforeFiles', 'afterFiles', 'fallback'], 'rewrites');
+  const rewrites = Object.fromEntries(['beforeFiles', 'afterFiles', 'fallback'].map(phase => [phase, compileList(rawRewrites[phase] === undefined ? [] : rawRewrites[phase], 'rewrite', `rewrites.${phase}`)]));
+  const result = { version: 1, headers, redirects, rewrites };
+  if (Buffer.byteLength(JSON.stringify(result)) > MAX_MANIFEST_BYTES) fail('manifest', 'compiled routes exceed 2 MiB');
+  return result;
+}

package/build/dev-worker.mjs

@@ -0,0 +1,18 @@
+import {build} from './index.mjs';
+import {closeIncrementalCompiler} from './incremental.mjs';
+import {realpath} from 'node:fs/promises';
+import {createDevInputSnapshot} from '../runtime/dev-file-changes.mjs';
+let builds=0,busy=false;
+process.on('message',async message=>{
+  if(message?.type!=='build'||busy)return;
+  busy=true;
+  try{
+    const started=performance.now();
+    const inputs=createDevInputSnapshot([message.root,await realpath(message.root)]);
+    await build(message.root,{dev:true,incremental:true,devInputs:inputs});
+    console.log(`PRNext built ${message.root} in ${((performance.now()-started)/1000).toFixed(2)}s`);
+    process.send({type:'result',ok:true,inputs:inputs.entries(),recycle:++builds>=24 || process.memoryUsage().rss>512*1024*1024});
+  }catch(error){process.send({type:'result',ok:false,error:error.stack||error.message,recycle:true});}
+  finally{busy=false;}
+});
+process.on('disconnect',async()=>{await closeIncrementalCompiler();process.exit();});

package/build/dev.mjs

@@ -0,0 +1,76 @@
+import { transformAsync } from '@babel/core';
+import refresh from 'react-refresh/babel';
+import { readFile, realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cachedAsyncTransform } from './transform-cache.mjs';
+import {inlineSourceMap} from './source-maps.mjs';
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+export const devClientFile = path.join(packageRoot, 'runtime/dev-client.mjs');
+
+/** Keep React renderers and framework contexts identical across rebuilt ESM chunks. */
+export function devSingletonsPlugin() {
+  return { name: 'prnext-development-singletons', setup(build) {
+    build.onLoad({ filter: /\.[cm]?js$/, namespace: 'file' }, async args => {
+      const filename = args.path.replaceAll(path.sep, '/');
+      if (!/\/node_modules\/(?:react|react-dom|react-refresh|react-server-dom-webpack)\//.test(filename) && !(args.path.startsWith(path.join(packageRoot, 'compat') + path.sep) && args.path.endsWith('.cjs'))) return;
+      const source = await readFile(args.path, 'utf8');
+      // These packages and adapters expose CommonJS entry points. ESM files are
+      // left alone; wrapping their declarations would change module semantics.
+      if (!/\b(?:module\.exports|exports\.)/.test(source)) return;
+      return { contents: `const __prnextModules=globalThis.__PRNEXT_DEV_MODULES__||=new Map();const __prnextKey=${JSON.stringify(filename)};if(__prnextModules.has(__prnextKey)){module.exports=__prnextModules.get(__prnextKey)}else{\n${source}\n__prnextModules.set(__prnextKey,module.exports);}`, loader: 'js', resolveDir: path.dirname(args.path) };
+    });
+  } };
+}
+
+function componentExports(program) {
+  let count = 0;
+  for (const statement of program.body) {
+    if (statement.type === 'ExportAllDeclaration') return false;
+    if (statement.type === 'ExportDefaultDeclaration') {
+      count++;
+      const value = statement.declaration;
+      const name = value.id?.name || (value.type === 'Identifier' ? value.name : '');
+      if (!/^[A-Z]/.test(name)) return false;
+    }
+    if (statement.type !== 'ExportNamedDeclaration' || statement.exportKind === 'type') continue;
+    if (statement.source) return false;
+    const declaration = statement.declaration;
+    const names = declaration?.type === 'VariableDeclaration' ? declaration.declarations.map(item => item.id.name)
+      : declaration?.id ? [declaration.id.name] : statement.specifiers.filter(item => item.exportKind !== 'type').map(item => item.local?.name);
+    for (const name of names) { count++; if (!name || !/^[A-Z]/.test(name)) return false; }
+  }
+  return count > 0;
+}
+
+/** The official React transform records hook signatures and refresh families. */
+export function createRefreshTransform(projectRoot) {
+  projectRoot = path.resolve(projectRoot);
+  const canonicalRoot = realpath(projectRoot).catch(() => projectRoot);
+  return async (source, filename) => {
+    if (filename.includes(`${path.sep}node_modules${path.sep}`) || filename.includes(`${path.sep}.prnext-build-`)) return source;
+    // Bundlers resolve symlinks (including /var -> /private/var on macOS).
+    // Compare against both spellings so temporary/linked apps still refresh.
+    const root = filename.startsWith(projectRoot + path.sep) ? projectRoot : await canonicalRoot;
+    if (!filename.startsWith(root + path.sep)) return source;
+    const hash = createHash('sha256').update(source).digest('hex');
+    return cachedAsyncTransform('fast-refresh',source,[projectRoot,filename],async () => {
+      const result = await transformAsync(source, { filename, babelrc: false, configFile: false,
+        ast: true, sourceMaps: true, sourceFileName:filename, sourceType: 'unambiguous',
+        parserOpts: { plugins: ['jsx', ...(/\.tsx?$/.test(filename) ? ['typescript'] : [])] },
+        plugins: [[refresh, { skipEnvCheck: true, refreshReg: '__prnextRefreshReg', refreshSig: '__prnextRefreshSig' }]],
+      });
+      const id = path.relative(root, filename).replaceAll(path.sep, '/');
+      // An ESM import changes webpack's interpretation of module.exports.
+      // Keep script/CommonJS inputs in their original module format.
+      const runtime = result.ast.program.sourceType === 'script'
+        ? `const{register:__prnextRegister,signature:__prnextRefreshSig,registerModule:__prnextRegisterModule}=require(${JSON.stringify(devClientFile)});`
+        : `import{register as __prnextRegister,signature as __prnextRefreshSig,registerModule as __prnextRegisterModule}from ${JSON.stringify(devClientFile)};`;
+      const strict = result.ast.program.directives.some(item => item.value.value === 'use strict') ? '"use strict";' : '';
+      const prefix = `${strict}${runtime}function __prnextRefreshReg(type,id){__prnextRegister(type,${JSON.stringify(id + ':')}+id)};\n`;
+      return inlineSourceMap(prefix + result.code + `\n__prnextRegisterModule(${JSON.stringify(id)},${JSON.stringify(hash)},${componentExports(result.ast.program)});\n`,{...result.map,mappings:';'+result.map.mappings});
+    });
+  };
+}

package/build/directory-cache.mjs

@@ -0,0 +1,29 @@
+import {readdir} from 'node:fs/promises';
+
+const entries=new Map();
+let bytes=0,hits=0,misses=0;
+const limit=1024*1024,countLimit=256;
+export const directoryCacheStats=()=>({entries:entries.size,bytes,hits,misses});
+export function clearDirectoryCache(){entries.clear();bytes=0;}
+
+/** Validate names on every scan: Linux directory timestamps and sizes may be
+ * identical across rapid additions/renames. A stat-only cache can miss routes.
+ * Keep bounded snapshots, with one readdir instead of two stat calls on misses.
+ * File contents remain handled separately by the source/configuration caches. */
+export async function readDirectory(directory){
+  const files=await readdir(directory,{withFileTypes:true});
+  const value=JSON.stringify(files.map(item=>[item.name,item.isDirectory()?'d':item.isFile()?'f':'o']));
+  let entry=entries.get(directory);
+  if(entry?.value===value){hits++;entries.delete(directory);entries.set(directory,entry);return decode(entry.value);}
+  misses++;
+  if(entry){entries.delete(directory);bytes-=entry.bytes;}
+  const size=2*(directory.length+value.length);
+  if(size<=64*1024){
+    while(entries.size && (entries.size>=countLimit || bytes+size>limit)){
+      const [key,old]=entries.entries().next().value;entries.delete(key);bytes-=old.bytes;
+    }
+    entries.set(directory,{value,bytes:size});bytes+=size;
+  }
+  return decode(value);
+}
+function decode(value){return JSON.parse(value).map(([name,kind])=>({name,isDirectory:()=>kind==='d',isFile:()=>kind==='f'}));}