@thomas.f/prnext 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,54 @@
+<a href="https://prnext.dev"><img src="https://prnext.dev/favicon.svg" alt="PRNext logo" width="80" height="80"></a>
+
+# PRNext
+
+[Website](https://prnext.dev) · [GitHub](https://github.com/Lorkydey/PRNext) · [Report an issue](https://github.com/Lorkydey/PRNext/issues)
+
+A Rust-powered runtime for Next.js projects, with React and npm modules running on Node.js.
+
+> **Very early alpha — 0.1.0-alpha.1**
+>
+> Built for experimentation and feedback, not production applications. Next.js compatibility is partial. Expect bugs, missing features and breaking changes.
+
+## Install and migrate
+
+Node.js 22+ is required. This alpha uses matching React, React DOM and React Server Components versions:
+
+```sh
+npm install @thomas.f/prnext@alpha react@19.3.0 react-dom@19.3.0 react-server-dom-webpack@19.3.0
+npx --no-install prn migrate --dry-run
+npx --no-install prn migrate
+npx --no-install prn check
+npx --no-install prn dev
+```
+
+The package provides both `prnext` and its shortcut `prn`. Migration backs up your package files and keeps Next.js and your application source. The preflight check does not guarantee full compatibility with your application.
+
+## Build and run
+
+```sh
+npx --no-install prn build
+npx --no-install prn start
+```
+
+Balanced is the default production profile. Choose a profile with:
+
+```sh
+npx --no-install prn start --profile balanced
+npx --no-install prn start --profile speed
+npx --no-install prn start --profile memory
+npx --no-install prn start --profile classic
+```
+
+## Platforms
+
+Prebuilt packages support macOS arm64/x64 and Linux glibc arm64/x64. Use WSL on Windows. Alpine/musl and native Windows do not yet have prebuilt packages. Linux binaries are built on Ubuntu 22.04 with glibc 2.35.
+
+Keep npm optional dependencies enabled: PRNext automatically installs the binary for your platform. Rust is not required to use the published package.
+
+## Links and feedback
+
+- Website and benchmarks: [prnext.dev](https://prnext.dev)
+- Source and contributions: [Lorkydey/PRNext](https://github.com/Lorkydey/PRNext)
+- Bug reports: [GitHub Issues](https://github.com/Lorkydey/PRNext/issues)
+- Questions and suggestions: [contact@heythomas.dev](mailto:contact@heythomas.dev)

package/build/action-exports.mjs

@@ -0,0 +1,107 @@
+import {generateMapped} from './source-maps.mjs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import generateImport from '@babel/generator';
+import * as t from '@babel/types';
+
+const generate = generateImport.default || generateImport;
+const astFor = (source, file) => parse(source, { sourceType: 'module', sourceFilename: file, plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(file) ? ['typescript'] : [])] });
+const exportName = node => node.name ?? node.value;
+
+/** Resolve wildcard exports statically, including cycles and ESM ambiguity rules. */
+export async function expandActionExports(source, file, resolve) {
+  if (!source.includes('use server') || !source.includes('export') || !source.includes('*')) return source;
+  const ast = astFor(source, file);
+  if (!ast.program.directives.some(item => item.value.value === 'use server') || !ast.program.body.some(item => t.isExportAllDeclaration(item) && item.exportKind !== 'type')) return source;
+  const graph = new Map([[file, { source, ast }]]);
+  const pending = [file];
+  let sourceBytes = 0;
+  for (let index = 0; index < pending.length; index++) {
+    const filename = pending[index];
+    const node = graph.get(filename);
+    node.source ??= await readFile(filename, 'utf8');
+    sourceBytes += Buffer.byteLength(node.source);
+    if (sourceBytes > 2 * 1024 * 1024) throw new Error('Server Action export graph exceeds 2 MiB');
+    node.ast ??= astFor(node.source, filename);
+    node.explicit = new Map(); node.stars = []; node.locals = new Map();
+    const imports = new Map(), resolutions = new Map();
+    async function target(specifier) {
+      if (resolutions.has(specifier)) return resolutions.get(specifier);
+      const result = await resolve(specifier, filename);
+      if (!result || !path.isAbsolute(result)) throw new Error(`Cannot enumerate Server Action exports from ${specifier} in ${filename}; use explicit named exports`);
+      if (!graph.has(result)) {
+        if (graph.size >= 256) throw new Error('Server Action export graph exceeds 256 modules');
+        graph.set(result, {}); pending.push(result);
+      }
+      resolutions.set(specifier, result);
+      return result;
+    }
+    for (const item of node.ast.program.body) {
+      const declaration = t.isExportNamedDeclaration(item) || t.isExportDefaultDeclaration(item) ? item.declaration : item;
+      if (t.isFunctionDeclaration(declaration) && declaration.id) node.locals.set(declaration.id.name, { id: filename + '#' + declaration.id.name, async: declaration.async && !declaration.generator });
+      if (t.isVariableDeclaration(declaration)) for (const binding of declaration.declarations) if (t.isIdentifier(binding.id)) {
+        node.locals.set(binding.id.name, t.isIdentifier(binding.init) ? { local: binding.init.name } :
+          { id: filename + '#' + binding.id.name, ...(t.isFunction(binding.init) ? { async: binding.init.async && !binding.init.generator } : t.isLiteral(binding.init) || t.isObjectExpression(binding.init) || t.isArrayExpression(binding.init) || t.isClassExpression(binding.init) ? { async: false } : {}) });
+      }
+      if (t.isClassDeclaration(declaration) && declaration.id) node.locals.set(declaration.id.name, { id: filename + '#' + declaration.id.name, async: false });
+      if (t.isImportDeclaration(item) && item.importKind !== 'type') for (const binding of item.specifiers) {
+        if (binding.importKind === 'type') continue;
+        imports.set(binding.local.name, { source: item.source.value, name: t.isImportDefaultSpecifier(binding) ? 'default' : t.isImportNamespaceSpecifier(binding) ? '*' : exportName(binding.imported) });
+      }
+    }
+    async function local(name, seen = new Set()) {
+      if (seen.has(name)) return { id: filename + '#' + name };
+      seen.add(name);
+      if (imports.has(name)) { const imported = imports.get(name); return { file: await target(imported.source), name: imported.name }; }
+      const value = node.locals.get(name);
+      return value?.local ? local(value.local, seen) : value || { id: filename + '#' + name };
+    }
+    for (const item of node.ast.program.body) {
+      if (item.exportKind === 'type') continue;
+      if (t.isExportAllDeclaration(item)) { node.stars.push({ source: item.source.value, file: await target(item.source.value), node: item }); continue; }
+      if (t.isExportDefaultDeclaration(item)) {
+        node.explicit.set('default', t.isIdentifier(item.declaration) ? await local(item.declaration.name) : { id: filename + '#default', ...(t.isFunction(item.declaration) ? { async: item.declaration.async && !item.declaration.generator } : {}) });
+      }
+      if (!t.isExportNamedDeclaration(item)) continue;
+      if (item.declaration && !t.isTSInterfaceDeclaration(item.declaration) && !t.isTSTypeAliasDeclaration(item.declaration) && !item.declaration.declare) {
+        for (const name of Object.keys(t.getOuterBindingIdentifiers(item.declaration))) node.explicit.set(name, await local(name));
+      }
+      for (const binding of item.specifiers) if (binding.exportKind !== 'type') {
+        node.explicit.set(exportName(binding.exported), item.source ? { file: await target(item.source.value), name: binding.local ? exportName(binding.local) : '*' } : await local(binding.local.name));
+      }
+    }
+  }
+  const names = new Set([...graph.values()].flatMap(node => [...node.explicit.keys()]));
+  if (names.size > 4096) throw new Error('Server Action export graph exceeds 4096 names');
+  function resolveExport(filename, name, seen = new Set()) {
+    const identity = filename + '\0' + name;
+    if (seen.has(identity)) return undefined;
+    // ESM ResolveExport shares resolveSet across sibling branches, not just
+    // ancestors. Visit each module/name once per resolution, including diamonds.
+    seen.add(identity);
+    const node = graph.get(filename), own = node.explicit.get(name);
+    if (own) return own.file ? own.name === '*' ? { id: own.file + '#namespace', async: false } : resolveExport(own.file, own.name, seen) : own;
+    if (name === 'default') return undefined;
+    let found;
+    for (const star of node.stars) {
+      const value = resolveExport(star.file, name, seen);
+      if (!value) continue;
+      if (value.ambiguous || (found && found.id !== value.id)) return { ambiguous: true };
+      found = value;
+    }
+    return found;
+  }
+  const root = graph.get(file), replacements = new Map(root.stars.map(star => [star.node, []]));
+  for (const name of names) {
+    if (name === 'default' || root.explicit.has(name)) continue;
+    const value = resolveExport(file, name);
+    if (!value || value.ambiguous) continue;
+    if (value.async === false) throw new Error(`Server Action export '${name}' must be an async function (${file}).`);
+    const origin = root.stars.find(star => resolveExport(star.file, name)?.id === value.id);
+    replacements.get(origin.node).push({ type: 'ExportSpecifier', local: t.isValidIdentifier(name) ? t.identifier(name) : t.stringLiteral(name), exported: t.stringLiteral(name) });
+  }
+  ast.program.body = ast.program.body.flatMap(item => replacements.has(item)
+    ? replacements.get(item).length ? [t.exportNamedDeclaration(null, replacements.get(item), item.source)] : [] : [item]);
+  return generateMapped(generate, ast, { comments: true }, source, file);
+}

package/build/actions.mjs

@@ -0,0 +1,214 @@
+import {cachedTransform} from './transform-cache.mjs';
+import {generateMapped} from './source-maps.mjs';
+import { parse } from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import generateModule from '@babel/generator';
+import * as t from '@babel/types';
+import { createHmac, createHash, randomBytes } from 'node:crypto';
+import path from 'node:path';
+
+const traverse = traverseModule.default || traverseModule;
+const generate = generateModule.default || generateModule;
+function hasDirective(node,value) { return node?.directives?.some(item=>item.value.value===value); }
+function removeDirective(node,value) { if(node?.directives) node.directives=node.directives.filter(item=>item.value.value!==value); }
+
+export function createServerActions({ projectRoot }) {
+  const salt = randomBytes(32);
+  const modules = new Map();
+  const actions = new Map();
+  const configured = process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY;
+  if (configured && (!/^[A-Za-z0-9+/]+={0,2}$/.test(configured) || ![16,24,32].includes(Buffer.from(configured,'base64').length))) throw new Error('NEXT_SERVER_ACTIONS_ENCRYPTION_KEY must be a base64-encoded 16, 24, or 32 byte AES key.');
+  const actionKey = configured ? Buffer.from(configured,'base64').toString('base64') : randomBytes(32).toString('base64');
+  function identity(file,name) { return createHmac('sha256',salt).update(path.relative(projectRoot,file).replaceAll(path.sep,'/')+'\0'+name).digest('hex'); }
+  function register(file,name,binding) {
+    const id=identity(file,name);
+    if(!actions.has(id)) actions.set(id,{id,file,binding});
+    return id;
+  }
+
+  function analyze(source,file) {
+    const key=file+'\0'+createHash('sha256').update(source).digest('hex');
+    if(modules.has(key))return modules.get(key);
+    const template=JSON.parse(cachedTransform('server-action-analysis',source,[projectRoot,file],()=>JSON.stringify(analyzeTemplate(source,file))));
+    const ids=new Map(template.registrations.map(item=>[item.id,register(file,item.name,item.binding)]));
+    let server=template.server;
+    for(const [previous,current]of ids)server=server.replaceAll(previous,current);
+    const result={...template,server,declared:template.declared.map(item=>({...item,id:ids.get(item.id)}))};
+    delete result.registrations;
+    modules.set(key,result);
+    return result;
+  }
+  function analyzeTemplate(source,file) {
+    const registrations=[],templateSalt=randomBytes(32);
+    function register(_file,name,binding) {
+      const id=createHmac('sha256',templateSalt).update(name).digest('hex');
+      registrations.push({name,binding,id});return id;
+    }
+    const ast=parse(source,{sourceType:'unambiguous',sourceFilename:file,plugins:['jsx',...(/\.tsx?$/.test(file)?['typescript']:[])]});
+    const moduleServer=hasDirective(ast.program,'use server');
+    const moduleClient=hasDirective(ast.program,'use client');
+    if(moduleServer&&moduleClient) throw new Error(`A module cannot use both 'use client' and 'use server': ${file}`);
+    let program;
+    traverse(ast,{Program(value){program=value;value.stop();}});
+    const registration=program.scope.generateUidIdentifier('registerServerReference');
+    const decrypt=program.scope.generateUidIdentifier('decryptBoundArgs');
+    const bind=program.scope.generateUidIdentifier('bindEncryptedReference');
+    const lifted=[];
+    const moduleExports=[];
+    let inlineCount=0;
+    let encrypted=false;
+
+    if(moduleServer) {
+      removeDirective(ast.program,'use server');
+      for(const statement of program.get('body')) {
+        if(statement.isExportAllDeclaration()) {
+          if(statement.node.exportKind==='type') { statement.remove(); continue; }
+          throw new Error(`Server Action wildcard exports must be resolved by the build graph (${file}).`);
+        }
+        if(statement.isExportDefaultDeclaration()) {
+          const declaration=statement.node.declaration;
+          const name=program.scope.generateUidIdentifier('defaultAction');
+          if(t.isFunctionDeclaration(declaration)) {
+            if(!declaration.async||declaration.generator) throw new Error(`Server Action default export must be an async function (${file}).`);
+            declaration.id ||= name;
+            moduleExports.push({name:'default',local:declaration.id.name});
+            statement.replaceWith(declaration);
+          } else {
+            if(t.isFunction(declaration)&&(!declaration.async||declaration.generator)) throw new Error(`Server Action default export must be an async function (${file}).`);
+            statement.replaceWith(t.variableDeclaration('const',[t.variableDeclarator(name,declaration)]));
+            moduleExports.push({name:'default',local:name.name});
+          }
+        } else if(statement.isExportNamedDeclaration()) {
+          if(statement.node.exportKind==='type') continue;
+          const declaration=statement.node.declaration;
+          if(declaration) {
+            if(t.isTSInterfaceDeclaration(declaration)||t.isTSTypeAliasDeclaration(declaration)||declaration.declare) continue;
+            for(const name of Object.keys(t.getOuterBindingIdentifiers(declaration))) moduleExports.push({name,local:name});
+            statement.replaceWith(declaration);
+          } else {
+            const imports=[];
+            for(const specifier of statement.node.specifiers) {
+              if(specifier.exportKind==='type') continue;
+              const name=specifier.exported.name??specifier.exported.value;
+              let local=specifier.local?.name;
+              if(statement.node.source) {
+                const binding=program.scope.generateUidIdentifier('importedAction');
+                imports.push(t.importSpecifier(binding,t.cloneNode(specifier.local)));
+                local=binding.name;
+              }
+              if(!local) throw new Error(`Unsupported Server Action export ${name} (${file}).`);
+              moduleExports.push({name,local});
+            }
+            if(imports.length) statement.replaceWith(t.importDeclaration(imports,statement.node.source)); else statement.remove();
+          }
+        }
+      }
+      program.scope.crawl();
+      for(const item of moduleExports) {
+        let binding=program.scope.getBinding(item.local);
+        let value;
+        const visited=new Set();
+        while(binding&&!visited.has(binding)) {
+          visited.add(binding);
+          value=binding.path.isVariableDeclarator()?binding.path.node.init:binding.path.node;
+          if(!t.isIdentifier(value)) break;
+          binding=program.scope.getBinding(value.name);
+        }
+        if(value&&!t.isImportSpecifier(value)&&!t.isImportDefaultSpecifier(value)&&(!t.isFunction(value)||!value.async||value.generator)) throw new Error(`Server Action export '${item.name}' must be an async function (${file}).`);
+      }
+    }
+
+    traverse(ast,{Function:{exit(functionPath){
+      if(!hasDirective(functionPath.node.body,'use server')) return;
+      if(moduleClient) throw new Error(`Inline 'use server' functions cannot be defined in a Client Component (${file}); import an action from a module marked 'use server'.`);
+      if(!functionPath.node.async||functionPath.node.generator) throw new Error(`Inline Server Actions must be async functions (${file}).`);
+      if(functionPath.isObjectMethod()||functionPath.isClassMethod()||functionPath.isClassPrivateMethod()) throw new Error(`Server Actions must be functions, not object or class methods (${file}).`);
+      removeDirective(functionPath.node.body,'use server');
+      const captures=new Map();
+      function capture(reference,name) {
+        if(name==='arguments'&&functionPath.isArrowFunctionExpression()) throw new Error(`Inline arrow Server Actions cannot capture arguments (${file}).`);
+        const binding=reference.scope.getBinding(name);
+        if(!binding||binding.scope===program.scope) return;
+        if(binding.path===functionPath||binding.path.node===functionPath.node) return;
+        if(binding.scope===functionPath.scope||binding.scope.path.findParent(parent=>parent===functionPath)) return;
+        captures.set(name,binding.kind==='const'?'const':'let');
+      }
+      functionPath.traverse({
+        ReferencedIdentifier(reference){ capture(reference,reference.node.name); },
+        AssignmentExpression(reference){for(const name of Object.keys(t.getBindingIdentifiers(reference.node.left)))capture(reference,name);},
+        UpdateExpression(reference){if(t.isIdentifier(reference.node.argument))capture(reference,reference.node.argument.name);},
+        ThisExpression(reference){ if(functionPath.isArrowFunctionExpression()) throw new Error(`Inline arrow Server Actions cannot capture this (${file}).`); },
+      });
+      const names=[...captures.keys()];
+      const exported=program.scope.generateUidIdentifier('inlineAction');
+      const id=register(file,`inline:${functionPath.node.start}:${inlineCount++}`,exported.name);
+      const args=program.scope.generateUidIdentifier('actionArgs');
+      const cipher=program.scope.generateUidIdentifier('encryptedClosure');
+      const original=t.cloneNode(functionPath.node,true);
+      if(t.isFunctionDeclaration(original)) original.type='FunctionExpression';
+      const body=[];
+      if(names.length) {
+        encrypted=true;
+        const values=program.scope.generateUidIdentifier('closureValues');
+        body.push(t.variableDeclaration('const',[t.variableDeclarator(values,t.awaitExpression(t.callExpression(decrypt,[t.stringLiteral(id),cipher])))]));
+        for(const [index,name] of names.entries()) body.push(t.variableDeclaration(captures.get(name),[t.variableDeclarator(t.identifier(name),t.memberExpression(values,t.numericLiteral(index),true))]));
+      }
+      body.push(t.returnStatement(t.callExpression(t.memberExpression(original,t.identifier('apply')),[t.unaryExpression('void',t.numericLiteral(0)),args])));
+      lifted.push(t.exportNamedDeclaration(t.functionDeclaration(exported,[...(names.length?[cipher]:[]),t.restElement(args)],t.blockStatement(body),false,true)));
+      lifted.push(t.expressionStatement(t.callExpression(registration,[exported,t.stringLiteral(id),t.nullLiteral()])));
+      function reference(value) {
+        const registered=t.callExpression(registration,[value,t.stringLiteral(id),t.nullLiteral()]);
+        return names.length?t.callExpression(bind,[registered,t.stringLiteral(id),t.arrowFunctionExpression([],t.arrayExpression(names.map(name=>t.identifier(name))))]):registered;
+      }
+      if(functionPath.isFunctionDeclaration()) {
+        if(!functionPath.node.id) throw new Error(`Anonymous inline Server Actions must be expressions (${file}).`);
+        let parent=functionPath.parentPath;
+        if(parent.isExportNamedDeclaration()||parent.isExportDefaultDeclaration()) parent=parent.parentPath;
+        if(!parent.isBlockStatement()&&!parent.isProgram()) throw new Error(`Inline Server Action declarations need a block scope (${file}).`);
+        parent.unshiftContainer('body',t.expressionStatement(reference(t.cloneNode(functionPath.node.id))));
+      } else {
+        functionPath.replaceWith(reference(t.cloneNode(functionPath.node,true)));
+        functionPath.skip();
+      }
+    }}});
+    const declared=moduleExports.map(item=>({...item,id:register(file,`export:${item.name}`,item.name)}));
+    if(!moduleServer&&!inlineCount) { return {server:source,declared:[],inline:false,registrations}; }
+    const imports=[t.importDeclaration([t.importSpecifier(registration,t.identifier('registerServerReference'))],t.stringLiteral('react-server-dom-webpack/server.node'))];
+    if(encrypted) imports.push(t.importDeclaration([t.importSpecifier(decrypt,t.identifier('decryptBoundArgs')),t.importSpecifier(bind,t.identifier('bindEncryptedReference'))],t.stringLiteral('prnext-internal:action-crypto')));
+    ast.program.body.unshift(...imports);
+    ast.program.body.push(...lifted);
+    // Internal references to exported actions must retain React's server marker
+    // and patched bind method too. Keep an existing marker on imported actions;
+    // each public alias still has its own stable proxy/manifest registration.
+    const registeredLocals=new Set();
+    for(const item of declared) {
+      if(registeredLocals.has(item.local)) continue;
+      registeredLocals.add(item.local);
+      ast.program.body.push(t.ifStatement(
+        t.binaryExpression('!==',t.memberExpression(t.identifier(item.local),t.identifier('$$typeof')),t.callExpression(t.memberExpression(t.identifier('Symbol'),t.identifier('for')),[t.stringLiteral('react.server.reference')])),
+        t.expressionStatement(t.callExpression(registration,[t.identifier(item.local),t.stringLiteral(item.id),t.nullLiteral()]))
+      ));
+    }
+    for(const item of declared) {
+      const exported=program.scope.generateUidIdentifier('serverAction');
+      const args=program.scope.generateUidIdentifier('args');
+      const wrapper=t.arrowFunctionExpression([t.restElement(args)],t.callExpression(t.identifier(item.local),[t.spreadElement(args)]),true);
+      ast.program.body.push(t.variableDeclaration('const',[t.variableDeclarator(exported,t.callExpression(registration,[wrapper,t.stringLiteral(item.id),t.nullLiteral()]))]));
+      ast.program.body.push(t.exportNamedDeclaration(null,[t.exportSpecifier(exported,t.stringLiteral(item.name))]));
+    }
+    const result={server:generateMapped(generate,ast,{comments:true},source,file),declared,inline:inlineCount>0,moduleServer,registrations};
+    return result;
+  }
+
+  return {
+    actions, actionKey,
+    transform(source,file,mode) {
+      if(!source.includes('use server')) return source;
+      const result=analyze(source,file);
+      if(mode==='rsc') return result.server;
+      if(result.moduleServer) return `import {createServerReference} from 'prnext-internal:action-${mode==='browser'?'client':'ssr'}';\n`+result.declared.map((item,index)=>`const action${index}=createServerReference(${JSON.stringify(item.id)});export {action${index} as ${JSON.stringify(item.name)}};`).join('\n');
+      if(result.inline) throw new Error(`Inline Server Actions cannot be imported into the client graph (${file}); move the action to a module marked 'use server'.`);
+      return source;
+    },
+  };
+}

package/build/app-config.mjs

@@ -0,0 +1,138 @@
+import { readFile } from 'node:fs/promises';
+import { parse } from '@babel/parser';
+import {validSamples} from '../compat/instant-samples.cjs';
+import { createHash } from 'node:crypto';
+
+const parsedConfigs = new Map();
+let parsedBytes = 0, parsedHits = 0, parsedMisses = 0;
+export const appConfigCacheStats = () => ({ entries: parsedConfigs.size, bytes: parsedBytes, hits: parsedHits, misses: parsedMisses });
+
+// Platform and cache modes without implemented semantics fail during scanning.
+const supported = new Map([
+  ['runtime', ['nodejs', 'edge']],
+  ['dynamic', ['auto', 'force-dynamic', 'force-static', 'error']],
+  ['revalidate', [false]],
+  ['dynamicParams', [true, false]],
+  ['instant', [true, false]],
+  ['fetchCache', ['auto', 'default-cache', 'only-cache', 'force-cache', 'force-no-store', 'default-no-store', 'only-no-store']],
+  ['preferredRegion', ['auto']],
+  ['maxDuration', []],
+  ['generateStaticParams', []],
+  ['experimental_ppr', [false]],
+]);
+
+function literal(node) {
+  while (['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'TypeCastExpression'].includes(node?.type)) node = node.expression;
+  if (node?.type === 'NullLiteral') return null;
+  if (node?.type === 'ArrayExpression') { const values = node.elements.map(literal); return values.includes(undefined) ? undefined : values; }
+  if (node?.type === 'ObjectExpression') {
+    const output = {};
+    for (const item of node.properties) {
+      if (item.type !== 'ObjectProperty' || item.computed || item.shorthand) return undefined;
+      const key = item.key.name ?? item.key.value, value = literal(item.value);
+      if (typeof key !== 'string' || value === undefined || key === '__proto__') return undefined;
+      Object.defineProperty(output, key, { value, enumerable: true });
+    }
+    return output;
+  }
+  return ['StringLiteral', 'BooleanLiteral', 'NumericLiteral'].includes(node?.type) ? node.value : undefined;
+}
+
+export async function validateAppConfig(file) {
+  const source = await readFile(file, 'utf8');
+  const digest = createHash('sha256').update(source).digest('hex');
+  const hit = parsedConfigs.get(file);
+  if (hit?.digest === digest) {
+    parsedHits++; parsedConfigs.delete(file); parsedConfigs.set(file, hit);
+    return JSON.parse(hit.json);
+  }
+  parsedMisses++;
+  if (hit) { parsedConfigs.delete(file); parsedBytes -= hit.size; }
+  const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file,
+    plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+  const locals = new Map();
+  const exports = [];
+  for (const statement of ast.program.body) {
+    const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+    if (declaration?.type === 'VariableDeclaration') for (const item of declaration.declarations) {
+      if (item.id.type !== 'Identifier') continue;
+      locals.set(item.id.name, literal(item.init));
+      if (statement.type === 'ExportNamedDeclaration') exports.push({ name: item.id.name, local: item.id.name });
+    }
+    if (statement.type !== 'ExportNamedDeclaration' || statement.exportKind === 'type') continue;
+    if (declaration?.type === 'FunctionDeclaration' || declaration?.type === 'ClassDeclaration') exports.push({ name: declaration.id.name });
+    for (const item of statement.specifiers) if (item.exportKind !== 'type') exports.push({
+      name: item.exported.name ?? item.exported.value, local: statement.source ? undefined : item.local?.name,
+    });
+  }
+  const config = {};
+  for (const item of exports) {
+    if (!supported.has(item.name)) continue;
+    const value = locals.get(item.local);
+    const allowed = supported.get(item.name);
+    if (item.name === 'instant') {
+      if (ast.program.directives.some(directive => directive.value.value === 'use client')) throw new Error(`instant cannot be exported by a Client Component (${file}).`);
+      if (value && typeof value === 'object' && Object.entries(value).every(([name, value]) => name === 'unstable_samples' ? validSamples(value) : name === 'level' ? ['warning', 'experimental-error'].includes(value) : ['unstable_disableValidation', 'unstable_disableDevValidation', 'unstable_disableBuildValidation'].includes(name) && value === true)) { config.instant = value; continue; }
+    }
+    if (item.name === 'generateStaticParams') {
+      if (ast.program.directives.some(directive => directive.value.value === 'use client')) throw new Error(`generateStaticParams cannot be exported by a Client Component (${file}).`);
+      config.generateStaticParams = true;
+      continue;
+    }
+    if (allowed.includes(value) || (item.name === 'revalidate' && Number.isSafeInteger(value) && value >= 0)) { config[item.name] = value; continue; }
+    throw new Error(`App Router export ${item.name} in ${file} is not supported with this value.${allowed.length ? ` Supported literal values: ${allowed.map(value => JSON.stringify(value)).join(', ')}${item.name === 'revalidate' ? ', or a nonnegative integer' : ''}.` : ''}`);
+  }
+  if (config.runtime === 'edge') {
+    if (config.revalidate !== undefined || ['force-static', 'error'].includes(config.dynamic)) throw new Error(`Edge Runtime does not support static generation or ISR configuration (${file}).`);
+  }
+  const json = JSON.stringify(config), size = Buffer.byteLength(file) + Buffer.byteLength(json);
+  if (size <= 64 * 1024) {
+    while (parsedConfigs.size && (parsedConfigs.size >= 256 || parsedBytes + size > 1024 * 1024)) {
+      const [key, value] = parsedConfigs.entries().next().value;
+      parsedConfigs.delete(key); parsedBytes -= value.size;
+    }
+    parsedConfigs.set(file, {digest, json, size}); parsedBytes += size;
+  }
+  return config;
+}
+
+export function mergeAppConfig(configs) {
+  const merged = { dynamic: 'auto', revalidate: false, dynamicParams: true, fetchCache: 'auto', forceNoStore: false };
+  const policies = new Set(configs.map(config => config.fetchCache).filter(Boolean));
+  if (configs.some(config => config.dynamic === 'force-dynamic')) policies.add('force-no-store');
+  if (policies.has('force-cache') && policies.has('force-no-store') || policies.has('only-cache') && policies.has('only-no-store')) {
+    throw new Error('Incompatible App Router fetchCache guarantees across route segments.');
+  }
+  let forceDynamic = false;
+  for (const config of configs) {
+    if (config.runtime === 'edge') merged.runtime = 'edge';
+    else if (config.runtime === 'nodejs') delete merged.runtime;
+    // The first explicit ancestor decides whether a blocking route is allowed.
+    // A child cannot weaken a parent's requirement for an instant shell.
+    if (config.instant !== undefined && merged.instant === undefined) merged.instant = config.instant;
+    if (config.dynamic !== undefined) merged.dynamic = config.dynamic;
+    if (config.dynamic === 'force-dynamic') forceDynamic = true;
+    if (typeof config.revalidate === 'number') merged.revalidate = merged.revalidate === false ? config.revalidate : Math.min(merged.revalidate, config.revalidate);
+    if (config.dynamicParams === false) merged.dynamicParams = false;
+    if (config.fetchCache !== undefined) merged.fetchCache = config.fetchCache;
+    if (config.fetchCache === 'force-no-store') merged.forceNoStore = true;
+  }
+  if (forceDynamic) merged.dynamic = 'force-dynamic';
+  if (policies.has('force-cache')) merged.fetchCache = 'force-cache';
+  else if (!merged.forceNoStore && !forceDynamic) {
+    if (policies.has('only-cache')) merged.fetchCache = 'only-cache';
+    if (policies.has('only-no-store')) merged.fetchCache = 'only-no-store';
+  }
+  if (forceDynamic || merged.forceNoStore) { merged.forceNoStore = true; merged.fetchCache = 'force-no-store'; }
+  if (merged.dynamic === 'error' && (merged.revalidate === 0 || merged.forceNoStore)) {
+    throw new Error("Incompatible App Router configuration: dynamic='error' cannot be combined with revalidate=0 or fetchCache='force-no-store'.");
+  }
+  if (!merged.forceNoStore) {
+    let parentNoStore = false;
+    for (const config of configs) {
+      if (parentNoStore && (config.fetchCache === 'auto' || config.fetchCache?.endsWith('-cache'))) throw new Error("Incompatible App Router configuration: a parent fetchCache='default-no-store' cannot have a child fetchCache='auto' or '*-cache'.");
+      if (config.fetchCache === 'default-no-store') parentNoStore = true;
+    }
+  }
+  return merged;
+}

package/build/app-routing.mjs

@@ -0,0 +1,119 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { mergeAppConfig } from './app-config.mjs';
+
+const group = part => /^\([^()]+\)$/.test(part);
+const signature = pattern => pattern.replace(/\[\[\.\.\.[^\]]+\]\]/g, '[[...]]').replace(/\[\.\.\.[^\]]+\]/g, '[...]').replace(/\[[^\]]+\]/g, '[]');
+export const rootLayoutId = file => file ? createHash('sha256').update(file).digest('hex').slice(0, 20) : undefined;
+export function appRouteParts(parts) {
+  let url = [], interception;
+  for (let index = 0; index < parts.length; index++) {
+    const part = parts[index];
+    if (part.startsWith('@') || group(part)) continue;
+    const marker = /^(\(\.\.\.\)|\(\.\)|(?:\(\.\.\))+)(.+)$/.exec(part);
+    if (marker) {
+      const source = '/' + url.join('/');
+      const levels = marker[1] === '(...)' ? url.length : marker[1] === '(.)' ? 0 : marker[1].length / 4;
+      if (levels > url.length) throw new Error(`Intercepting route ${parts.join('/')} traverses above the app root.`);
+      url = [...url.slice(0, url.length - levels), marker[2]];
+      interception = { source, anchor: parts.slice(0, index).join('/'), marker: marker[1], ...(interception ? { parent: interception } : {}) };
+    } else url.push(part.replace(/^%5f/i, '_'));
+  }
+  return { url, interception };
+}
+
+function compatible(left, right, prefix = false) {
+  const a = left.split('/').filter(Boolean), b = right.split('/').filter(Boolean);
+  for (let index = 0; index < Math.min(a.length, b.length); index++) {
+    if (a[index].startsWith('[...') || a[index].startsWith('[[...') || b[index].startsWith('[...') || b[index].startsWith('[[...')) return true;
+    if (!a[index].startsWith('[') && !b[index].startsWith('[') && a[index] !== b[index]) return false;
+  }
+  return prefix ? a.length <= b.length : a.length === b.length || a.at(-1)?.startsWith('[[...') || b.at(-1)?.startsWith('[[...');
+}
+
+/** Build one public route for all slots sharing a pathname, with a pruned component tree. */
+export function scanAdvancedAppRoutes({ root, appRoot, directories, configs, routes, patterns, validatePattern }) {
+  const nodes = new Map();
+  function node(directory) {
+    if (nodes.has(directory)) return nodes.get(directory);
+    const parts = directory ? directory.split('/') : [];
+    const info = appRouteParts(parts);
+    const files = directories.get(directory)?.files || {};
+    const value = { path: directory, segment: parts.at(-1) || '', pattern: '/' + info.url.join('/'), files,
+      layoutId: rootLayoutId(files.layout),
+      config: Object.fromEntries(['layout', 'page'].filter(name => files[name]).map(name => [name, configs.get(files[name]) || {}])), children: [], slots: {},
+      ...(info.interception ? { interception: info.interception } : {}) };
+    nodes.set(directory, value);
+    if (parts.length) {
+      const parent = node(parts.slice(0, -1).join('/'));
+      if (value.segment.startsWith('@')) {
+        const name = value.segment.slice(1);
+        if (!name || name === 'children' || !/^[A-Za-z_$][\w$-]*$/.test(name)) throw new Error(`Invalid parallel route slot ${value.segment} in ${directory}.`);
+        parent.slots[name] = value;
+      } else parent.children.push(value);
+    }
+    return value;
+  }
+  node('');
+  for (const directory of directories.keys()) node(directory);
+  const leaves = [];
+  for (const value of nodes.values()) {
+    if (!value.files.page && !value.files.route) continue;
+    if (value.files.page && value.files.route) throw new Error(`App page and Route Handler conflict in ${value.path}.`);
+    const file = value.files.page || value.files.route;
+    value.pattern = validatePattern(appRouteParts(value.path.split('/').filter(Boolean)).url, path.relative(root, file));
+    if (value.files.route) {
+      if (value.interception) throw new Error(`Route Handlers cannot be intercepted: ${file}.`);
+      const key = signature(value.pattern);
+      if (patterns.has(key)) throw new Error(`Conflicting routes: ${patterns.get(key)} and ${file}.`);
+      patterns.set(key, file);
+      routes.push({ id: `app-api-${createHash('sha256').update(value.pattern).digest('hex').slice(0, 12)}`, pattern: value.pattern, kind: 'api', router: 'app', file,
+        cacheConfig: mergeAppConfig([configs.get(file) || {}]), handlerConfig: configs.get(file) || {} });
+    } else leaves.push(value);
+  }
+  const publicPatterns = new Map();
+  for (const leaf of leaves) {
+    const key = signature(leaf.pattern);
+    if (!publicPatterns.has(key)) publicPatterns.set(key, { pattern: leaf.pattern, leaves: [] });
+    const collection = publicPatterns.get(key).leaves;
+    const channel = leaf.path.split('/').map((part, index, parts) => part.startsWith('@') ? parts.slice(0, index + 1).join('/') : '').filter(Boolean).join('|');
+    if (!leaf.interception && collection.some(other => !other.interception && other.channel === channel)) throw new Error(`Conflicting App routes ${leaf.files.page} and another page in ${channel || 'children'}.`);
+    leaf.channel = channel;
+    collection.push(leaf);
+  }
+  function chain(leaf) {
+    const parts = leaf.path ? leaf.path.split('/') : [];
+    return Array.from({ length: parts.length + 1 }, (_, index) => nodes.get(parts.slice(0, index).join('/'))).filter(Boolean);
+  }
+  function prune(value, pattern) {
+    const children = value.children.map(child => prune(child, pattern)).filter(Boolean);
+    const slots = Object.fromEntries(Object.entries(value.slots).map(([name, child]) => [name, prune(child, pattern) || { path: child.path, segment: child.segment, pattern: child.pattern, files: {}, children: [], slots: {} }]));
+    const page = value.files.page && compatible(value.pattern, pattern) ? value.files.page : undefined;
+    const defaultFile = value.files.default && compatible(value.pattern, pattern, true) ? value.files.default : undefined;
+    if (value.path && !page && !defaultFile && !children.length && !Object.keys(slots).length && !value.segment.startsWith('@') && !compatible(value.pattern, pattern, true)) return null;
+    const { route, page: ignoredPage, default: ignoredDefault, ...files } = value.files;
+    return { ...value, files: { ...files, ...(page ? { page } : {}), ...(defaultFile ? { default: defaultFile } : {}) }, children, slots };
+  }
+  for (const [key, item] of publicPatterns) {
+    if (patterns.has(key)) throw new Error(`Conflicting routes: ${patterns.get(key)} and ${item.pattern} (App Router).`);
+    patterns.set(key, item.leaves[0].files.page);
+    const primary = leaves.find(leaf => !leaf.channel && !leaf.interception && leaf.pattern === item.pattern)
+      || leaves.find(leaf => !leaf.channel && !leaf.interception && compatible(leaf.pattern, item.pattern))
+      || item.leaves.find(leaf => !leaf.interception) || item.leaves[0];
+    // Native matching uses one name per public URL. Keep each slot's own names
+    // in its component tree, but choose the canonical children names publicly.
+    if (signature(primary.pattern) === key) item.pattern = primary.pattern;
+    const parents = chain(primary);
+    const segments = parents.filter(value => !value.segment.startsWith('@') && !value.interception).map(value => {
+      const { page, route, default: defaultFile, ...files } = value.files;
+      return { segment: value.segment, path: value.path, ...files, ...(files.layout ? { staticConfig: configs.get(files.layout) || {} } : {}) };
+    });
+    if (!segments.some(segment => segment.layout)) throw new Error(`App route ${item.pattern} needs a root layout.`);
+    const activeLeaves = leaves.filter(leaf => !leaf.interception && compatible(leaf.pattern, item.pattern));
+    const configuration = [...new Set(activeLeaves.flatMap(leaf => [...chain(leaf).map(parent => parent.files.layout).filter(Boolean), leaf.files.page]))];
+    routes.push({ id: `app-page-${createHash('sha256').update(item.pattern).digest('hex').slice(0, 12)}`, pattern: item.pattern, kind: 'page', router: 'app', file: primary.files.page,
+      segments, pageConfig: configs.get(primary.files.page) || {}, cacheConfig: mergeAppConfig(configuration.map(file => configs.get(file) || {})),
+      routing: prune(nodes.get(''), item.pattern), parallel: true, interception: item.leaves.some(leaf => !!leaf.interception),
+      interceptionOnly: activeLeaves.length === 0 });
+  }
+}