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

package/build/create.mjs

@@ -0,0 +1,239 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { packageManifest } from '../native/resolve.mjs';
+import { supportedNode } from '../native/diagnostics.mjs';
+import { npmCommand } from '../native/npm.mjs';
+
+export const createHelp = `Usage: prnext create <directory> [--js] [--no-install] [--json]
+
+Create a minimal App Router project and install its dependencies with npm.
+TypeScript is the default; --js creates a JavaScript project.
+The directory must be absent or completely empty. Existing files are never replaced.
+--no-install prepares files without running npm or accessing the network.
+Inside an existing workspace, use --no-install and its own package manager.
+
+  npx @thomas.f/prnext create my-app
+  cd my-app
+  npm run dev
+`;
+
+export function parseCreateArgs(args, cwd = process.cwd()) {
+  const flags = new Set(), positional = [];
+  let literal = false;
+  for (const arg of args) {
+    if (literal) positional.push(arg);
+    else if (arg === '--') literal = true;
+    else if (['--no-install', '--js', '--json'].includes(arg)) {
+      if (flags.has(arg)) throw new Error(`Duplicate create option: ${arg}`);
+      flags.add(arg);
+    } else if (arg.startsWith('-')) throw new Error(`Unknown create option: ${arg}`);
+    else positional.push(arg);
+  }
+  if (positional.length !== 1 || !positional[0].trim() || /[\0\r\n]/.test(positional[0])) throw new Error('Provide one project directory: prnext create my-app');
+  return { directory: path.resolve(cwd, positional[0]), options: { install: !flags.has('--no-install'), typescript: !flags.has('--js'), json: flags.has('--json') } };
+}
+
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+async function info(file, options) {
+  try { return await lstat(file, options); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function physicalDirectory(directory, missing = false) {
+  // macOS exposes standard directories through root-owned /private aliases.
+  // Resolve only those exact system targets; every user-controlled descendant
+  // still goes through the strict no-symlink walk below, on every write.
+  if (process.platform === 'darwin') {
+    const alias = /^\/(?:var|tmp|etc)(?=\/|$)/.exec(directory)?.[0];
+    if (alias && (await info(alias))?.isSymbolicLink() && await realpath(alias) === `/private${alias}`) {
+      directory = `/private${directory}`;
+    }
+  }
+  const root = path.parse(directory).root;
+  const inspected = [];
+  let current = root;
+  for (const part of path.relative(root, directory).split(path.sep).filter(Boolean)) {
+    if (process.platform === 'win32' && (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) || /[<>:"|?*]|[. ]$/.test(part))) throw new Error(`Invalid Windows directory name: ${part}`);
+    current = path.join(current, part);
+    const entry = await info(current, { bigint: true });
+    if (!entry && missing) continue;
+    if (!entry?.isDirectory() || entry.isSymbolicLink()) throw new Error(`Project directories must not be files, symbolic links or junctions: ${current}`);
+    inspected.push([current, entry]);
+  }
+  if (!missing) {
+    const canonical = await realpath(directory);
+    if (!samePath(canonical, directory)) {
+      if (process.platform !== 'win32') throw new Error('Use a physical project directory without symbolic links or junctions.');
+      // DOS 8.3 names are directory aliases, not reparse points. Accept the
+      // expanded name only after rechecking every observed directory identity
+      // and proving that the canonical target is the same physical directory.
+      for (const [file, original] of inspected) {
+        const observed = await info(file, { bigint: true });
+        if (!observed?.isDirectory() || observed.isSymbolicLink() || !sameFile(original, observed)) throw new Error(`Project directory changed during creation: ${file}`);
+      }
+      const original = inspected.at(-1)?.[1] || await info(directory, { bigint: true });
+      const resolved = await info(canonical, { bigint: true });
+      if (!original?.isDirectory() || original.isSymbolicLink() || original.ino === 0n || !resolved?.isDirectory() || resolved.isSymbolicLink() || !sameFile(original, resolved)) throw new Error('Use a physical project directory without symbolic links or junctions.');
+    }
+  }
+}
+
+async function parentWorkspace(directory) {
+  for (let current = path.dirname(directory); ; current = path.dirname(current)) {
+    const workspace = await info(path.join(current, 'pnpm-workspace.yaml'));
+    if (workspace) return current;
+    const file = path.join(current, 'package.json'), entry = await info(file);
+    if (entry) {
+      if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 1024 * 1024) throw new Error(`Cannot safely inspect parent package.json: ${file}`);
+      let manifest;
+      try { manifest = JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, '')); }
+      catch { throw new Error(`Parent package.json is invalid: ${file}`); }
+      if (manifest.workspaces) return current;
+    }
+    if (current === path.dirname(current)) return null;
+  }
+}
+
+function projectName(directory) {
+  const name = path.basename(directory).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+|[._-]+$/g, '').slice(0, 100);
+  return !name || ['node_modules', 'favicon.ico'].includes(name) ? 'prnext-app' : name;
+}
+const json = value => JSON.stringify(value, null, 2) + '\n';
+
+function projectFiles(name, typescript) {
+  const extension = typescript ? 'tsx' : 'jsx';
+  const scripts = { dev: 'prnext dev', build: 'prnext build', start: 'prnext start', check: 'prnext check', ...(typescript ? { typecheck: 'prnext typecheck' } : {}) };
+  const manifest = { name, version: '0.0.0', private: true, type: 'module', scripts,
+    dependencies: { [packageManifest.name]: packageManifest.version, ...Object.fromEntries(Object.entries(packageManifest.peerDependencies).filter(([name])=>!packageManifest.peerDependenciesMeta?.[name]?.optional)) },
+    ...(typescript ? { devDependencies: { typescript: '^5.9.0', '@types/node': '^22.0.0', '@types/react': '^19.0.0', '@types/react-dom': '^19.0.0' } } : {}),
+    engines: { node: packageManifest.engines.node } };
+  const files = new Map([
+    ['package.json', json(manifest)],
+    [`app/layout.${extension}`, `import './globals.css';\n${typescript ? "import type { ReactNode } from 'react';\n" : ''}
+export const metadata = { title: 'My PRNext app', description: 'A React application built with PRNext.' };
+
+export default function RootLayout({ children }${typescript ? ': { children: ReactNode }' : ''}) {
+  return <html lang="en"><body>{children}</body></html>;
+}
+`],
+    [`app/page.${extension}`, `export default function Home() {
+  return <main><h1>PRNext</h1><p>Edit <code>app/page.${extension}</code> to get started.</p></main>;
+}
+`],
+    ['app/globals.css', `:root { color-scheme: dark; font-family: system-ui, sans-serif; background: #0a0a0a; color: #ededed; }
+* { box-sizing: border-box; }
+body { margin: 0; }
+main { max-width: 64rem; margin: auto; padding: clamp(2rem, 8vw, 6rem) 1.5rem; }
+h1 { font-size: clamp(2.5rem, 8vw, 4rem); letter-spacing: -.04em; }
+p { line-height: 1.6; }
+code { font-size: .95em; }
+`],
+    ['.gitignore', 'node_modules/\n.prnext/\n.prnext-types/\n.prnext-dev/\n.prnext-cache/\n.env*\n!.env.example\n*.tsbuildinfo\n'],
+    ['README.md', `# ${name}\n\nA minimal PRNext application.\n\nRun \`npm install\` if dependencies have not been installed, then:\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nEdit \`app/page.${extension}\`. Use the local URL printed by the server.\n\n\`\`\`sh\nnpm run check\n${typescript ? 'npm run typecheck\n' : ''}npm run build\nnpm start\n\`\`\`\n\nUse another port with \`npm run dev -- --port 3001\` when needed.\n\n[PRNext documentation](https://prnext.dev) · Installed AI guide: \`npx --no-install prnext docs --ai\`.\nPRNext is experimental; Next.js compatibility is partial.\n`],
+    ['AGENTS.md', `# PRNext project\n\nThis application uses \`@thomas.f/prnext\`. Before changing routing, configuration, data fetching or deployment, read the installed guide at \`node_modules/@thomas.f/prnext/AI.md\` or run:\n\n\`\`\`sh\nnpx --no-install prnext docs --ai\nnpx --no-install prnext docs --ai --list\n\`\`\`\n\nRead only the relevant topic with \`npx --no-install prnext docs --ai <topic>\`. The installed documentation is version-specific; do not assume full Next.js compatibility. Preserve the project's package manager and lockfile.\n`],
+  ]);
+  if (typescript) files.set('tsconfig.json', json({ compilerOptions: { target: 'ES2022', lib: ['DOM', 'DOM.Iterable', 'ES2022'], module: 'ESNext', moduleResolution: 'Bundler', jsx: 'preserve', strict: true, noEmit: true, esModuleInterop: true, skipLibCheck: true }, include: ['**/*.ts', '**/*.tsx'], exclude: ['node_modules', '.prnext', '.prnext-dev', '.prnext-cache'] }));
+  return files;
+}
+
+function abortError() { const error = new Error('Project creation canceled.'); error.name = 'AbortError'; return error; }
+function aborted(signal) { if (signal?.aborted) throw abortError(); }
+
+/** Run npm without a shell; a canceled command waits for its own installer tree. */
+export async function installProject(directory, { signal, onOutput = () => {} } = {}) {
+  aborted(signal);
+  // npm resolves its working directory physically. Keep its environment on
+  // that same path so macOS aliases cannot split the lock tree.
+  directory = await realpath(directory);
+  aborted(signal);
+  const env = { ...process.env, INIT_CWD: directory, PWD: directory };
+  for (const key of Object.keys(env)) if (/^npm_config_(?:workspace|workspaces|global|prefix)$/i.test(key)) delete env[key];
+  const npm = npmCommand(env);
+  await new Promise((resolve, reject) => {
+    // The generated package.json already anchors npm's local project here.
+    // npm 10 on Windows treats an explicit --prefix as its global top and can
+    // add the project to its own dependencies even with --global=false.
+    const child = spawn(npm.command, [...npm.args, 'install', '--workspaces=false', '--global=false'], { cwd: directory, env, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    let tail = '', timer, canceling = false;
+    const receive = stream => chunk => { tail = (tail + chunk).slice(-16000); onOutput(String(chunk), stream); };
+    child.stdout.on('data', receive('stdout'));
+    child.stderr.on('data', receive('stderr'));
+    function terminate(force) {
+      if (!child.pid) return;
+      if (process.platform === 'win32') {
+        if (child.exitCode !== null || child.signalCode) return;
+        const executable = path.join(env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe');
+        const killer = spawn(executable, ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        killer.on('error', () => child.kill());
+      } else {
+        try { process.kill(-child.pid, force ? 'SIGKILL' : 'SIGTERM'); } catch (error) { if (error.code !== 'ESRCH') child.kill(force ? 'SIGKILL' : 'SIGTERM'); }
+      }
+    }
+    function cancel() { canceling = true; terminate(false); timer ||= setTimeout(() => terminate(true), 5000); }
+    function cleanup() { clearTimeout(timer); signal?.removeEventListener('abort', cancel); }
+    child.once('error', error => { cleanup(); reject(error); });
+    child.once('close', (code, childSignal) => {
+      // A detached lifecycle script can close npm's pipes before it exits.
+      // Do not let npm's exit cancel escalation for that remaining group.
+      if ((canceling || signal?.aborted) && process.platform !== 'win32') terminate(true);
+      cleanup();
+      if (canceling || signal?.aborted) reject(abortError());
+      else if (code === 0) resolve();
+      else reject(new Error(`npm install failed (${childSignal || code}).${tail.trim() ? '\n' + tail.trim() : ''}`));
+    });
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+  });
+}
+
+export async function createProject(directory, options = {}, services = {}) {
+  const root = path.resolve(directory), typescript = options.typescript !== false, install = options.install !== false;
+  aborted(options.signal);
+  const nodeVersion = services.nodeVersion || process.version;
+  if (!supportedNode(nodeVersion)) throw new Error(`Node ${nodeVersion} is unsupported. Use Node ${packageManifest.engines.node}.`);
+  await physicalDirectory(root, true);
+  const existing = await info(root);
+  if (existing && (await readdir(root)).length) throw new Error(`Project directory must be empty; no files were changed: ${root}`);
+  if (install && await parentWorkspace(root)) throw new Error('Automatic installation inside an existing workspace is not supported. Use --no-install, then add the project with the workspace package manager. No files were changed.');
+  aborted(options.signal);
+  await mkdir(root, { recursive: true });
+  await physicalDirectory(root);
+  const lockPath = path.join(root, '.prnext-create.lock');
+  const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW || 0), 0o600);
+  const locked = await lock.stat();
+  try {
+    if ((await readdir(root)).some(name => name !== '.prnext-create.lock')) throw new Error(`Project directory is no longer empty; existing files were preserved: ${root}`);
+    const name = projectName(root), files = projectFiles(name, typescript);
+    for (const [relative, content] of files) {
+      aborted(options.signal);
+      await physicalDirectory(root);
+      const target = path.join(root, relative), parent = path.dirname(target);
+      await physicalDirectory(parent, true);
+      await mkdir(parent, { recursive: true });
+      await physicalDirectory(parent);
+      const file = await open(target, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW || 0), 0o644);
+      try { await file.writeFile(content, 'utf8'); } finally { await file.close(); }
+    }
+    const report = { ok: true, status: 'prepared', root, name, typescript, files: [...files.keys()], installed: false, next: install ? ['npm run dev'] : ['npm install', 'npm run dev'] };
+    if (install) {
+      try {
+        aborted(options.signal);
+        await (services.runInstall || installProject)(root, { signal: options.signal, onOutput: options.onOutput });
+        aborted(options.signal);
+        report.installed = true;
+        report.status = 'created';
+      } catch (error) {
+        report.ok = false;
+        report.status = error.name === 'AbortError' || options.signal?.aborted ? 'cancelled' : 'install-failed';
+        report.error = error.message;
+        report.next = ['npm install', 'npm run dev'];
+      }
+    }
+    return report;
+  } finally {
+    await lock.close();
+    const current = await info(lockPath);
+    if (current?.isFile() && !current.isSymbolicLink() && sameFile(current, locked)) await unlink(lockPath);
+  }
+}

package/build/css-modules.mjs

@@ -1,13 +1,15 @@
 import { build as bundle } from 'esbuild';
-import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import { mkdir, writeFile, realpath, readdir, readFile } 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';
+import { createStyleProcessor, resolveStandardBrowserTargets, stylesheetPattern, moduleStylesheetPattern } from './styles.mjs';
 import {rename} from '../runtime/fs.mjs';
 import {randomUUID} from 'node:crypto';
 import {rm} from 'node:fs/promises';
+import {cachedCompilation} from './compilation-cache.mjs';
+import {compactCssModule,globalCssNames} from './compact-css.mjs';
 
 const assetLoaders = Object.fromEntries(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'].map(ext => [ext, 'file']));
 
@@ -23,13 +25,34 @@ async function resolveCss(esbuild, args) {
 }
 
 /** One cached CSS compilation supplies identical class maps to the server and the browser. */
-export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions, cssEngine }) {
-  const cache = new Map();
-  const processor = createStyleProcessor({ projectRoot, sassOptions, cssEngine });
+export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions, cssEngine, dev = false, config = {} }) {
+  const cache = new Map(), compactNames = new Map();
+  let targets;
+  const browserTargets=()=>targets ??= Promise.resolve().then(()=>resolveStandardBrowserTargets(projectRoot));
+  const processor = createStyleProcessor({ projectRoot, sassOptions, cssEngine, browserTargets });
   const hash = file => createHash('sha256').update(path.relative(projectRoot, file).replaceAll(path.sep, '/')).digest('hex').slice(0, 12);
+  let eligibility;
+  async function cacheEligible() {
+    if (dev || cssEngine==='postcss' || config.webpack || Object.keys(config.turbopack?.rules || {}).length || process.env.BROWSERSLIST_CONFIG || process.env.BROWSERSLIST_STATS || /\b(?:extends|stats)\b/i.test(process.env.BROWSERSLIST || '')) return false;
+    // A user PostCSS plugin can read arbitrary files, glob directories or use
+    // network/time without declaring dependencies. Its output is never cached.
+    const names = await readdir(projectRoot);
+    if (names.some(name => /^(?:postcss\.config|\.postcssrc)(?:\.|$)/.test(name))) return false;
+    try { if (JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8')).postcss !== undefined) return false; }
+    catch (error) { if (error.code !== 'ENOENT') return false; }
+    return true;
+  }
+  const validMapping = value => {try{const parsed=JSON.parse(value);return parsed&&typeof parsed==='object'&&!Array.isArray(parsed)&&Object.values(parsed).every(value=>typeof value==='string');}catch{return false;}};
+  const validResult = value => value && typeof value.mapping === 'string' && value.mapping.length <= 16*1024*1024 && validMapping(value.mapping) && typeof value.css === 'string' && value.css.length <= 16*1024*1024
+    && Array.isArray(value.compactNames) && value.compactNames.length <= 65536 && value.compactNames.every(item=>Array.isArray(item)&&item.length===2&&typeof item[0]==='string'&&item[0].length<=4096&&typeof item[1]==='string'&&/^p[\w-]{10}$/.test(item[1]))
+    && Array.isArray(value.watchFiles) && value.watchFiles.length <= 4096 && value.watchFiles.every(file => typeof file==='string' && path.isAbsolute(file) && !file.includes('\0') && !/\.s[ac]ss$/i.test(file))
+    && Array.isArray(value.assets) && value.assets.length <= 4096 && value.assets.every(asset => asset && typeof asset.name === 'string'
+      && asset.name && asset.name === path.basename(asset.name) && !/[\\/\0<>:"|?*#]/.test(asset.name) && asset.name !== '.' && asset.name !== '..'
+      && typeof asset.data === 'string' && asset.data.length<=24*1024*1024 && asset.data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(asset.data))
+    && new Set(value.assets.map(asset=>asset.name)).size===value.assets.length && value.assets.reduce((sum,asset)=>sum+asset.data.length,0)<=48*1024*1024;
 
   async function compile(file) {
-    const dependencies=new Set([file]);
+    const dependencies=new Set([file]), globals = new Set();
     const result = await bundle({
       absWorkingDir: projectRoot,
       stdin: { contents: `import styles from ${JSON.stringify(file)}; export default styles;`, resolveDir: projectRoot, loader: 'js' },
@@ -57,11 +80,13 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
           });
           esbuild.onLoad({ filter: /.*/, namespace: 'prnext-local-css' }, async args => {
             const transformed = await processor.process(args.pluginData.source);
+            if (!dev) globalCssNames(transformed.css, {local:true}, globals);
             for(const file of transformed.watchFiles)dependencies.add(file);
             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);
+            if (!dev) globalCssNames(transformed.css, {local:false}, globals);
             for(const file of transformed.watchFiles)dependencies.add(file);
             return { contents: transformed.css, loader: 'css', resolveDir: path.dirname(args.path), watchFiles: transformed.watchFiles };
           });
@@ -77,18 +102,37 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
     // 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 });
+    const compact = dev ? {mapping:module.exports.default,css:stylesheet.text,names:[]} : compactCssModule(stylesheet.text,module.exports.default,{globals});
+    const mapping = JSON.stringify({ ...compact.mapping, ...(await processor.process(file)).exports });
+    const assets = [];
     for (const output of result.outputFiles) {
       if (output === javascript || output === stylesheet) continue;
-      const target=path.join(stage,'assets',path.basename(output.path)),temporary=target+'.'+randomUUID()+'.tmp';
-      try{await writeFile(temporary,output.contents);await rename(temporary,target);}finally{await rm(temporary,{force:true});}
+      assets.push({name:path.basename(output.path),data:Buffer.from(output.contents).toString('base64')});
     }
-    return { mapping, css: stylesheet.text,watchFiles:[...dependencies] };
+    return { mapping, css: compact.css,compactNames:compact.names,watchFiles:[...dependencies],assets };
   }
 
   function get(file) {
-    if (!cache.has(file)) cache.set(file, compile(file));
+    if (!cache.has(file)) cache.set(file, (async () => {
+      eligibility ??= cacheEligible();
+      const enabled = await eligibility && /\.css$/i.test(file);
+      const result = await cachedCompilation({root:projectRoot,kind:'css-modules',inputs:[file],excluded:[path.resolve(projectRoot,config.distDir || '.prnext'),...(config.output==='export'?[path.join(projectRoot,'out')]:[])],styleTargets:true,settings:{file,assetBase,cssEngine:cssEngine || 'auto',...(enabled?{browserTargets:await browserTargets()}:{})},
+        enabled,reason:dev?'development':'custom-style-pipeline',validate:validResult,
+        bytes:value=>Buffer.byteLength(value.mapping)+Buffer.byteLength(value.css)+Buffer.byteLength(JSON.stringify(value.compactNames))+value.assets.reduce((sum,asset)=>sum+Buffer.byteLength(asset.data,'base64'),0),
+        produce:async()=>{const value=await compile(file);return {value,dependencies:value.watchFiles};}});
+      await mkdir(path.join(stage,'assets'),{recursive:true});
+      for(const [original,short] of result.compactNames || []) {
+        if(compactNames.has(short)&&compactNames.get(short)!==original)throw new Error('CSS Module compact-name collision across modules.');
+        compactNames.set(short,original);
+      }
+      for (const asset of result.assets) {
+        const target=path.join(stage,'assets',asset.name),temporary=target+'.'+randomUUID()+'.tmp';
+        try{await writeFile(temporary,Buffer.from(asset.data,'base64'));await rename(temporary,target);}finally{await rm(temporary,{force:true});}
+      }
+      // Keep the original public result and release replay-only binary payloads.
+      // The per-build mapping cache must not retain a base64 copy of every asset.
+      return {mapping:result.mapping,css:result.css,watchFiles:result.watchFiles};
+    })());
     return cache.get(file);
   }
 

package/build/deployment-assets.mjs

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const INDEX = 'deployment-assets.json';
+const MAX_FILES = 1024, MAX_BYTES = 64 * 1024 * 1024, MAX_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_AGE = 60 * 60 * 1000, MAX_GENERATIONS = 2;
+// Only build-owned, immutable code/styles. Never JSON, maps, HTML, public/ or server/.
+const safeName = value => typeof value === 'string' && value.length < 240 && /^[a-zA-Z0-9_.-]+-[a-zA-Z0-9]{8,64}\.(?:js|mjs|css|woff2?|ttf|otf|eot|png|jpe?g|avif|webp|gif|svg|ico|wasm)$/.test(value);
+const assetKey = name => process.platform === 'win32' ? name.toLowerCase() : name;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+async function regular(file, limit) {
+  const info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > limit) return;
+  return info;
+}
+async function indexAt(directory) {
+  try {
+    if (!await regular(path.join(directory, INDEX), 1024 * 1024)) return;
+    const value = JSON.parse(await readFile(path.join(directory, INDEX), 'utf8'));
+    if (value.version !== 1 || !Array.isArray(value.generations) || value.generations.length > 6) return;
+    for (const generation of value.generations) {
+      if (typeof generation.id !== 'string' || generation.id.length > 128 || !Number.isSafeInteger(generation.createdAt) || !Array.isArray(generation.files) || generation.files.length > MAX_FILES) return;
+      const seen = new Set();
+      for (const file of generation.files) {
+        if (!safeName(file.name) || seen.has(assetKey(file.name)) || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > MAX_FILE_BYTES || !/^[a-f0-9]{64}$/.test(file.hash)) return;
+        seen.add(assetKey(file.name));
+      }
+    }
+    return value;
+  } catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) { /* Corrupt previous metadata is an optional retention miss. */ } }
+}
+
+/** Copy only public immutable assets into a stage, before its atomic publication. */
+export async function retainDeploymentAssets({ stage, destination, manifest, policy, now = Date.now() }) {
+  if (manifest.dev) return { generations: 0, files: 0, bytes: 0 };
+  const maxAge = (policy && policy.maxAge !== undefined ? policy.maxAge * 1000 : MAX_AGE);
+  const maxGenerations = policy && policy.maxGenerations !== undefined ? policy.maxGenerations : MAX_GENERATIONS;
+  const maxBytes = policy && policy.maxBytes !== undefined ? policy.maxBytes : MAX_BYTES;
+  const assets = path.join(stage, 'assets');
+  const assetInfo = await lstat(assets);
+  if (!assetInfo.isDirectory() || assetInfo.isSymbolicLink()) throw new Error('Deployment assets must be a regular directory');
+  const current = { id: manifest.cacheId, createdAt: now, eligible: true, files: [] };
+  let indexedBytes = 0;
+  for (const name of (await readdir(assets)).sort()) {
+    if (!safeName(name)) {
+      // Maps/manifests do not participate in executable chunk graphs. Unknown
+      // content-addressed media and auxiliary directories make retention unsafe.
+      if (/\.(?:map|json|html|txt|gz|br)$/.test(name)) continue;
+      current.eligible = false; current.files = []; break;
+    }
+    const file = path.join(assets, name), info = await regular(file, MAX_FILE_BYTES);
+    if (!info || (indexedBytes += info.size) > 256 * 1024 * 1024) { current.eligible = false; current.files = []; break; }
+    const bytes = await readFile(file);
+    current.files.push({ name, bytes: bytes.length, hash: hash(bytes) });
+    if (current.files.length > MAX_FILES) { current.eligible = false; current.files = []; break; }
+  }
+  const previousRoot = await lstat(path.join(destination, 'assets')).catch(() => null);
+  const previous = !current.eligible || policy === false || !previousRoot?.isDirectory() || previousRoot.isSymbolicLink() ? undefined : await indexAt(destination), generations = [current], known = new Map(current.files.map(file => [assetKey(file.name), file]));
+  const retained = Object.create(null); let bytes = 0, count = 0;
+  for (const generation of previous?.generations || []) {
+    if (generation.eligible !== true || generations.length > maxGenerations || generation.id === current.id || generation.createdAt > now || now - generation.createdAt >= maxAge) continue;
+    if (generation.files.some(file => { const value = known.get(assetKey(file.name)); return value && (value.hash !== file.hash || value.bytes !== file.bytes); })) continue;
+    const candidates = generation.files.filter(file => !known.has(assetKey(file.name)));
+    const size = candidates.reduce((sum, file) => sum + file.bytes, 0);
+    if (bytes + size > maxBytes || count + candidates.length > MAX_FILES) continue;
+    const verified = [];
+    for (const file of candidates) {
+      const source = path.join(destination, 'assets', file.name);
+      try {
+        if (!await regular(source, MAX_FILE_BYTES)) continue;
+        const contents = await readFile(source);
+        if (contents.length !== file.bytes || hash(contents) !== file.hash) continue;
+        verified.push({file, contents});
+      } catch { /* An unreadable previous asset is an optional retention miss. */ }
+    }
+    // An incomplete previous generation cannot promise a working chunk graph.
+    if (verified.length !== candidates.length) continue;
+    for (const {file, contents} of verified) {
+      await writeFile(path.join(assets, file.name), contents, {flag:'wx'});
+      known.set(assetKey(file.name), file); retained[file.name] = generation.createdAt + maxAge;
+      bytes += file.bytes; count++;
+    }
+    generations.push(generation);
+  }
+  manifest.config.retainedAssets = retained;
+  await writeFile(path.join(stage, INDEX), JSON.stringify({ version: 1, generations }) + '\n');
+  return { generations: generations.length - 1, files: count, bytes };
+}

package/build/deployment-config.mjs

@@ -0,0 +1,18 @@
+const defaults=Object.freeze({maxAge:3600,maxGenerations:2,maxBytes:64*1024*1024});
+const limits={maxAge:[1,86400],maxGenerations:[1,5],maxBytes:[1024,256*1024*1024]};
+
+/** Retain only bounded, immutable public assets; false revokes all carry-over. */
+export function validateDeploymentRetention(value){
+  if(value===false)return false;
+  if(value===undefined)return {...defaults};
+  if(!value||typeof value!=='object'||Array.isArray(value)||![Object.prototype,null].includes(Object.getPrototypeOf(value)))throw new TypeError('deploymentRetention must be false or an object.');
+  const output={...defaults};
+  for(const key of Reflect.ownKeys(value)){
+    if(!Object.hasOwn(limits,key))throw new TypeError(`deploymentRetention.${String(key)} is not supported.`);
+    if(value[key]===undefined)continue;
+    const [minimum,maximum]=limits[key];
+    if(!Number.isSafeInteger(value[key])||value[key]<minimum||value[key]>maximum)throw new TypeError(`deploymentRetention.${key} must be an integer from ${minimum} to ${maximum}.`);
+    output[key]=value[key];
+  }
+  return output;
+}

package/build/dev-css-update.mjs

@@ -31,7 +31,7 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
   for(const dependency of manifest.devDependencies||[])for(const file of dependency.files)if(file.endsWith('.css'))known.add(path.join(root,file));
   if(changed.some(file=>!known.has(path.join(root,file))))return fallback('unknown-style-dependency');
   if(!selected.length)return fallback('unknown-style-dependency');
-  const stage=destination,modules=createCssModules({projectRoot:root,stage,assetBase:manifest.config.assetBase,cssEngine});
+  const stage=destination,modules=createCssModules({projectRoot:root,stage,assetBase:manifest.config.assetBase,cssEngine,dev:true});
   try{
     await snapshot(source,stage);
     for(const previous of manifest.devStyles.modules.filter(module=>(module.watchFiles||[module.file]).some(file=>changedPaths.has(file)))){
@@ -70,7 +70,9 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
     old.buildId=buildId;
     const changedNames=new Set(selected.map(([name])=>name));
     const revise=urls=>urls.map(url=>changedNames.has(path.posix.basename(url.split('?')[0]))?url.split('?')[0]+'?v='+buildId:url);
-    for(const page of old.pages)page.css=revise(page.css);if(old.app)old.app.css=revise(old.app.css);
+    const reviseScopes=scopes=>scopes?.map(scope=>({...scope,css:revise(scope.css)}));
+    for(const page of old.pages)page.css=revise(page.css);if(old.app){old.app.css=revise(old.app.css);for(const route of old.app.routes||[]){route.css=revise(route.css);if(route.cssScopes)route.cssScopes=reviseScopes(route.cssScopes);}}
+    next.routes=next.routes.map(route=>({...route,css:revise(route.css||[]),...(route.cssScopes?{cssScopes:reviseScopes(route.cssScopes)}:{})}));
     await writeFile(path.join(stage,'assets',path.basename(next.devClient)),JSON.stringify(old));
     const protectedNames=new Set([path.basename(baseClient),path.basename(next.devClient)]),history=[];
     for(const name of await readdir(path.join(stage,'assets')))if(/^dev-manifest-.*\.json$/.test(name)&&!protectedNames.has(name)){const info=await stat(path.join(stage,'assets',name));history.push({name,size:info.size,time:info.mtimeMs});}

package/build/dev-dependencies.mjs

@@ -8,7 +8,7 @@ export function recordDevDependencies(state,options,result){
     for(const item of input.imports||[])if(!item.external)imports.add(absolute(item.path));
     state.devDependencies.set(file,imports);
   }
-  for(const [name,output]of Object.entries(result.metafile.outputs))if(name.endsWith('.css')){
+  for(const [name,output]of Object.entries(result.metafile.outputs))if(name.endsWith('.css')&&path.resolve(options.absWorkingDir||state.root,name).startsWith(path.join(state.stage,'assets')+path.sep)){
     const inputs=Object.keys(output.inputs||{}).filter(file=>file!=='<stdin>'),imported=new Set();
     for(const input of inputs)for(const item of result.metafile.inputs[input]?.imports||[])if(item.kind==='import-rule')imported.add(item.path);
     const roots=inputs.filter(input=>!imported.has(input));

package/build/dev-discovery.mjs

@@ -19,9 +19,9 @@ export async function discoverDevelopment(root) {
   try {
     const config=await loadProjectConfig(root,{dev:true,envMode});
     const project=await scanProject(root,{basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n,devAppFiles:new Set()});
-    // Dynamic middleware/rewrite destinations and intercepted/parallel trees
-    // need the complete graph until the gateway can resolve their routing RPC.
-    const eager=!!project.middleware || !!config.rewrites || project.routes.some(route=>route.parallel||route.interception);
+    // Destinations unknown before routing are represented by deferred entries.
+    // Their worker asks the compiler only after middleware has run once.
+    const eager=false;
     return {project,eager,cssFast:!config.webpack&&!Object.keys(config.turbopack?.rules||{}).length,config:{basePath:config.basePath,assetPrefix:config.assetPrefix,i18n:config.i18n,distDir:config.distDir,
       onDemandEntries:config.onDemandEntries,typescript:config.typescript,typedRoutes:config.typedRoutes,cssEngine:config.cssEngine}};
   } finally {restore();}

package/build/dev.mjs

@@ -5,7 +5,8 @@ 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';
+import {inlineSourceMap,extractSourceMap} from './source-maps.mjs';
+import {TraceMap,originalPositionFor} from '@jridgewell/trace-mapping';
 
 const packageRoot = fileURLToPath(new URL('../', import.meta.url));
 export const devClientFile = path.join(packageRoot, 'runtime/dev-client.mjs');
@@ -25,10 +26,14 @@ function namedDefaultComponents({types:t}){
     }
   }}}};
 }
-function sourceElements(id){return ({types:t})=>({visitor:{JSXOpeningElement(node){
+function sourceElements(id,trace){return ({types:t})=>({visitor:{JSXOpeningElement(node){
   const name=node.node.name;
   if(name.type!=='JSXIdentifier'||!/^[a-z]/.test(name.name)||node.node.attributes.some(attribute=>attribute.type==='JSXAttribute'&&attribute.name.name==='data-prnext-source'))return;
-  const start=node.node.loc?.start;if(!start)return;
+  let start=node.node.loc?.start;if(!start)return;
+  // React Compiler and custom loaders may move JSX before instrumentation.
+  // Follow their map back to the editable source; generated, unmapped elements
+  // must not send the inspector to an invented line in the user's component.
+  if(trace){const original=originalPositionFor(trace,start);if(original.line==null||original.column==null)return;start=original;}
   node.node.attributes.push(t.jsxAttribute(t.jsxIdentifier('data-prnext-source'),t.stringLiteral(`${id}:${start.line}:${start.column+1}`)));
 }}});}
 
@@ -41,8 +46,9 @@ export function createSourceLocationTransform(projectRoot){
     const root=filename.startsWith(projectRoot+path.sep)?projectRoot:await canonicalRoot;
     if(!filename.startsWith(root+path.sep))return source;
     const id=path.relative(root,filename).split(path.sep).join('/');
-    return cachedAsyncTransform('dev-source-elements',source,[root,filename,'v1'],async()=>{
-      const result=await transformAsync(source,{filename,babelrc:false,configFile:false,sourceMaps:true,sourceFileName:filename,sourceType:'unambiguous',parserOpts:{plugins:['jsx',...(/\.tsx?$/.test(filename)?['typescript']:[])]},plugins:[sourceElements(id)]});
+    return cachedAsyncTransform('dev-source-elements',source,[root,filename,'v2-original-locations'],async()=>{
+      const input=extractSourceMap(source),trace=input.map?new TraceMap(input.map):undefined;
+      const result=await transformAsync(source,{filename,babelrc:false,configFile:false,sourceMaps:true,sourceFileName:filename,sourceType:'unambiguous',parserOpts:{plugins:['jsx',...(/\.[cm]?tsx?$/.test(filename)?['typescript']:[])]},plugins:[sourceElements(id,trace)]});
       return inlineSourceMap(result.code,result.map);
     });
   };
@@ -96,12 +102,13 @@ export function createRefreshTransform(projectRoot, { generation,forceGeneration
     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');
-    const transformed = await cachedAsyncTransform('fast-refresh',source,[projectRoot,filename,'source-elements-v2'],async () => {
+    const transformed = await cachedAsyncTransform('fast-refresh',source,[projectRoot,filename,'source-elements-v3-original-locations'],async () => {
       const id = path.relative(root, filename).replaceAll(path.sep, '/');
+      const input=extractSourceMap(source),trace=input.map?new TraceMap(input.map):undefined;
       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: [namedDefaultComponents,[refresh, { skipEnvCheck: true, refreshReg: '__prnextRefreshReg', refreshSig: '__prnextRefreshSig' }],sourceElements(id)],
+        parserOpts: { plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] },
+        plugins: [namedDefaultComponents,[refresh, { skipEnvCheck: true, refreshReg: '__prnextRefreshReg', refreshSig: '__prnextRefreshSig' }],sourceElements(id,trace)],
       });
       // An ESM import changes webpack's interpretation of module.exports.
       // Keep script/CommonJS inputs in their original module format.

package/build/dynamic.mjs

@@ -67,7 +67,7 @@ export function transformDynamicImports(source, filename, { projectRoot, mode =
 
 function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
   const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: filename,
-    plugins: ['jsx', ...(/\.tsx?$/.test(filename) ? ['typescript'] : [])] });
+    plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] });
   const relative = path.relative(projectRoot || process.cwd(), filename).replaceAll(path.sep, '/');
   let changed = false;
   traverse(ast, {

package/build/edge.mjs

@@ -60,7 +60,7 @@ function validateUncached(source,file,reactMode) {
 }
 
 /** Bundle the entire application graph as Web ESM before entering the V8 realm. */
-export async function compileEdge({ file, outfile, projectRoot, dev = false, defineEnvironment = {}, defaultExport = false, reactMode, plugins = [], transformSource }) {
+export async function compileEdge({ file, outfile, projectRoot, dev = false, defineEnvironment = {}, defaultExport = false, reactMode, plugins = [], transformSource, transformTypedHelpers = false }) {
   const runtime = path.resolve(path.dirname(outfile), '../runtime');
   await mkdir(runtime, { recursive: true });
   try { await access(path.join(runtime, 'edge-vm.cjs')); }
@@ -85,7 +85,7 @@ export async function compileEdge({ file, outfile, projectRoot, dev = false, def
     mainFields: ['browser', 'module', 'main'], logLevel: 'silent', metafile: true,
     define: { 'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'), ...defineEnvironment, 'process.env.NEXT_RUNTIME': '"edge"' },
     plugins: [...plugins, { name: 'prnext-edge', setup(builder) {
-      applicationEntry(builder,readCompilerFile);
+      applicationEntry(builder,readCompilerFile,{transformTypedHelpers});
       builder.onResolve({ filter: /.*/ }, args => {
         if (builtin.has(args.path) || args.path.startsWith('node:')) return { errors: [{ text: `Node.js module ${args.path} cannot run in the Edge Runtime (${args.importer}).` }] };
         if (reactMode && ['react', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom', 'react-server-dom-webpack/server', 'react-server-dom-webpack/server.node'].includes(args.path)) return { path: args.path, namespace: 'prnext-edge-react' };
@@ -112,7 +112,7 @@ export async function compileEdge({ file, outfile, projectRoot, dev = false, def
         : names[args.path].map(name => `export const ${name}=globalThis.__PRNEXT_EDGE_HOST.${args.path}.${name};`).join('\n') }));
       builder.onLoad({ filter: /\.[cm]?[jt]sx?$/, namespace: 'file' }, async args => {
         let source = args.prnextSource ?? await readFile(args.path, 'utf8');
-        if (transformSource) source = await transformSource(source, args.path, builder);
+        if (transformSource) source = await transformSource(source, args.path, builder, {loaderOutput:args.prnextSource!==undefined});
         if (!trusted.has(args.path)) source = validate(source, args.path, reactMode);
         return { contents: source, loader: /\.[cm]?tsx?$/.test(args.path) ? 'tsx' : 'jsx', resolveDir: path.dirname(args.path) };
       });

package/build/fonts.mjs

@@ -51,7 +51,7 @@ export function createFonts({ projectRoot, stage, assetBase }) {
   }
   async function transformSource(source, file) {
     if (/(?:^|[/\\])pages[/\\]_document\.[cm]?[jt]sx?$/.test(file)) throw new Error('next/font cannot be used in pages/_document. Define fonts in pages/_app or a page component.');
-    const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file, plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+    const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file, plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(file) ? ['typescript'] : [])] });
     let program;
     traverse(ast, { Program(value) { program = value; value.stop(); } });
     const imports = [], calls = [];