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

package/build/dev-css-update.mjs

@@ -1,14 +1,15 @@
 import {build as bundle} from 'esbuild';
-import {readFile,writeFile,rm,stat,readdir} from 'node:fs/promises';
+import {readFile,writeFile,rm,stat} from 'node:fs/promises';
 import path from 'node:path';
 import {randomUUID} from 'node:crypto';
 import {rename} from '../runtime/fs.mjs';
 import {createCssModules} from './css-modules.mjs';
 import {recordDevDependencies,developmentStyleDependencies} from './dev-dependencies.mjs';
 import {writeBuildOutput} from './output-contract.mjs';
+import {createStyleOverlay,StyleOverlayFallback} from './dev-css-assets.mjs';
 
 /** Publish only styles when all JS-visible class maps remain identical. */
-export async function tryDevCssUpdate({root,source,destination,manifest,changed,sequence,cssEngine,snapshot,onFallback=()=>{}}){
+export async function tryDevCssUpdate({root,source,baseSource=source,destination,manifest,changed,sequence,cssEngine,onFallback=()=>{}}){
   const fallback=code=>{onFallback(code);return undefined;};
   if(!changed.length||changed.some(file=>!file.endsWith('.css'))||!manifest.devStyles?.bundles.length||manifest.app?.globalError?.css?.length)return;
   if(!manifest.config.assetBase.startsWith('/'))return fallback('external-asset-base');
@@ -31,9 +32,10 @@ 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});
+  let overlay;
   try{
-    await snapshot(source,stage);
+    overlay=await createStyleOverlay({root,source,baseSource,destination,manifest,plans,selected});
     for(const previous of manifest.devStyles.modules.filter(module=>(module.watchFiles||[module.file]).some(file=>changedPaths.has(file)))){
       if(!previous.file.endsWith('.css')){await rm(stage,{recursive:true,force:true});return fallback('stylesheet-language');}
       if((await modules.compile(previous.file)).mapping!==previous.mapping){await rm(stage,{recursive:true,force:true});return fallback('css-module-exports');}
@@ -42,7 +44,7 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
     for(const [name,files]of selected){
       const options={absWorkingDir:root,stdin:{contents:files.map(file=>`@import ${JSON.stringify(file.replace(/^prnext-compiled-css:/,'prnext-css:'))};`).join('\n'),resolveDir:root,loader:'css'},outfile:path.join(stage,'assets',name),bundle:true,write:false,metafile:true,logLevel:'silent',publicPath:manifest.config.assetBase,assetNames:'[name]-[hash]',loader:Object.fromEntries(['.png','.jpg','.jpeg','.svg','.gif','.webp','.avif','.woff','.woff2','.ttf'].map(ext=>[ext,'file'])),plugins:[modules.plugin(true)]};
       const result=await bundle(options);recordDevDependencies(state,options,result);
-      for(const output of result.outputFiles){const temporary=output.path+'.'+randomUUID()+'.tmp';try{await writeFile(temporary,output.contents);await rename(temporary,output.path);}finally{await rm(temporary,{force:true});}}
+      await overlay.recordBundle(name,result);
     }
     const compiled=await modules.mappings();
     if(compiled.some(value=>!manifest.devStyles.modules.some(previous=>previous.file===value.file&&previous.mapping===value.mapping))){await rm(stage,{recursive:true,force:true});return fallback('css-module-exports');}
@@ -51,7 +53,8 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
       for(const module of updated)if(files.includes(module.file))for(const file of module.watchFiles)if(!files.includes(file))files.push(file);
       dependencies.set(name,files);
     }
-    const buildId=randomUUID(),baseClient=manifest.devStyles.baseClient||manifest.devClient,next={...manifest,buildId,devSequence:sequence,devClient:manifest.config.assetBase+'/dev-manifest-'+buildId+'.json',outputDirectory:stage,devStyles:{baseClient,bundles:plans,dependencies:[...dependencies],modules:updated}};
+    const assets=await overlay.finish();
+    const buildId=randomUUID(),baseClient=manifest.devStyles.baseClient||manifest.devClient,next={...manifest,buildId,devSequence:sequence,devClient:manifest.config.assetBase+'/dev-manifest-'+buildId+'.json',outputDirectory:stage,devStyles:{baseClient,overlay:assets,bundles:plans,dependencies:[...dependencies],modules:updated}};
     // Keep route invalidation conservative as CSS imports are added or removed.
     // Unchanged routes retain their original dependency arrays.
     next.devDependencies=(manifest.devDependencies||[]).map(route=>{
@@ -66,18 +69,19 @@ export async function tryDevCssUpdate({root,source,destination,manifest,changed,
       }
       return {...route,files:[...files]};
     });
-    const old=JSON.parse(await readFile(path.join(source,'assets',path.basename(manifest.devClient)),'utf8'));
+    let old;
+    try{old=JSON.parse(await readFile(path.join(source,'assets',path.basename(manifest.devClient)),'utf8'));}
+    catch(error){if(error.code==='ENOENT'||error instanceof SyntaxError)throw new StyleOverlayFallback('missing-style-manifest');throw error;}
+    if(!Array.isArray(old?.pages)||old.pages.some(page=>!Array.isArray(page.css))||old.app&&(!Array.isArray(old.app.css)||!Array.isArray(old.app.routes)||old.app.routes.some(route=>!Array.isArray(route.css))))throw new StyleOverlayFallback('invalid-style-manifest');
     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});}
-    history.sort((a,b)=>b.time-a.time);let bytes=0;
-    for(let i=0;i<history.length;i++){bytes+=history[i].size;if(i>=32||bytes>4*1024*1024)await rm(path.join(stage,'assets',history[i].name));}
     const temporary=path.join(stage,'manifest.'+buildId+'.tmp');await writeFile(temporary,JSON.stringify(next));await rename(temporary,path.join(stage,'manifest.json'));
-    await rm(path.join(stage,'build-output.json'));await writeBuildOutput(stage,next);
+    await writeBuildOutput(stage,next);
     return next;
-  }catch(error){await rm(stage,{recursive:true,force:true});throw error;}
+  }catch(error){if(overlay)await rm(stage,{recursive:true,force:true});if(error instanceof StyleOverlayFallback)return fallback(error.code);throw error;}
 }

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-lazy-build.mjs

@@ -0,0 +1,77 @@
+import { mkdir, readdir, lstat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { compileApp } from './app.mjs';
+import { configureCompiler } from './compiler.mjs';
+import { createCssModules } from './css-modules.mjs';
+import { createFonts } from './fonts.mjs';
+import { createImages } from './images.mjs';
+import { discardLazyBuild } from '../runtime/dev-lazy-staging.mjs';
+import { loadEnvConfig } from '../runtime/env.mjs';
+
+// Only the latest successful ordinary generation per project is reusable.
+// This private compiler-process registry is not part of browser metadata or IPC.
+const contexts = new Map();
+const CONTEXT_LIMIT = 8, FILE_LIMIT = 16384, BYTE_LIMIT = 128 * 1024 * 1024;
+export function forgetLazyBuildContext(root) {
+  if (root === undefined) contexts.clear(); else contexts.delete(root);
+}
+export function rememberLazyBuildContext(root, { manifest, config, environment, tsconfig, envMode }) {
+  contexts.delete(root);
+  if (!manifest.devLazy || !manifest.dev || !config.experimental.lazyDynamicImports) return;
+  while (contexts.size >= CONTEXT_LIMIT) contexts.delete(contexts.keys().next().value);
+  contexts.set(root, { config, environment, tsconfig, envMode, cacheId: manifest.cacheId,
+    buildId: manifest.buildId, session: manifest.devSession,
+    manifestConfig: structuredClone(manifest.config) });
+}
+/** Reuse the validated configuration of the running generation, not its routes. */
+export async function tryBuildLazyGraph(root, { base, request, devInputs, devSession,
+  devActionSecret, incremental = true } = {}) {
+  if (!base || typeof base.cacheId !== 'string' || !request) throw Error('Invalid deferred build generation');
+  const context = contexts.get(root);
+  // Compiler recycling loses its private context. The caller retains the ordinary
+  // build path for this recovery case; it must never guess another generation.
+  if (!context || context.cacheId !== base.cacheId || context.session !== devSession) return;
+  // Preserve the running generation's env-file mode for supported build-time
+  // hooks. The enclosing build() scope restores the caller's env on every exit.
+  loadEnvConfig(root,{dev:true,mode:context.envMode,inputs:devInputs});
+  const { config, environment, tsconfig } = context;
+  const stage = path.join(root, '.prnext-build-' + randomUUID());
+  try {
+    await mkdir(path.join(stage, '.entries'), { recursive: true });
+    const manifest = { version: 1, dev: true, buildId: context.buildId,
+      cacheId: context.cacheId, devSession, config: structuredClone(context.manifestConfig),
+      routes: [], prerendered: [] };
+    const project = { root, routes: [] };
+    configureCompiler({ config, root, stage, buildId: context.buildId, dev: true,
+      incremental, devInputs, tsconfig, assetBase: manifest.config.assetBase });
+    const fonts = createFonts({ projectRoot: root, stage, assetBase: manifest.config.assetBase });
+    const cssModules = createCssModules({ projectRoot: root, stage,
+      assetBase: manifest.config.assetBase, sassOptions: config.sassOptions,
+      cssEngine: config.cssEngine, dev: true, config });
+    const images = await createImages({ projectRoot: root, stage,
+      assetBase: manifest.config.assetBase, config: config.images });
+    await compileApp({ project, stage, manifest, cssModules, fonts, images, dev: true,
+      devActionSecret, reactCompiler: config.reactCompiler, defineEnvironment: environment,
+      moduleResolution: config.turbopack, serverExternalPackages: config.serverExternalPackages,
+      lazyDynamicImports: true, devLazyRequest: request, devLazyOnly: true });
+    const files = [];
+    let bytes = 0;
+    // This unpublished stage contains only this deferred graph, never other
+    // routes or a copied framework runtime. Publication uses this exact receipt.
+    for (const entry of await readdir(path.join(stage, 'assets'), { withFileTypes: true })) {
+      if (!entry.isFile() || files.length >= FILE_LIMIT) throw Error('Invalid or excessive deferred output assets');
+      const info = await lstat(path.join(stage, 'assets', entry.name));
+      bytes += info.size;
+      if (!info.isFile() || bytes > BYTE_LIMIT) throw Error('Deferred output exceeds the 128 MiB generation budget');
+      files.push({ name: entry.name, bytes: info.size });
+    }
+    files.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    return { ...manifest, outputDirectory: stage, devLazyTemporary: true,
+      devLazyAssets: { version: 1, baseCacheId: context.cacheId, files } };
+  } catch (error) {
+    try { await discardLazyBuild(root, { outputDirectory: stage, devLazyTemporary: true }); }
+    catch (cleanupError) { error.cleanupError = cleanupError; error.message += '; deferred compiler staging cleanup also failed'; }
+    throw error;
+  }
+}

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

@@ -59,17 +59,19 @@ function loaderBody(loader) {
 }
 
 /** Add shared hydration IDs without resolving, evaluating or eagerly importing loaders. */
-export function transformDynamicImports(source, filename, { projectRoot, mode = 'browser' } = {}) {
+export function transformDynamicImports(source, filename, { projectRoot, mode = 'browser',dev=false } = {}) {
   if (![...sources].some(name => source.includes(name))) return source;
   projectRoot ||= process.cwd();
-  return cachedTransform('dynamic',source,[filename,projectRoot,mode],()=>transformDynamicImportsUncached(source,filename,{projectRoot,mode}));
+  return cachedTransform('dynamic',source,[filename,projectRoot,mode,dev],()=>transformDynamicImportsUncached(source,filename,{projectRoot,mode,dev}));
 }
 
-function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
+function transformDynamicImportsUncached(source, filename, {projectRoot,mode,dev}) {
   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, '/');
+  const developmentRevision=dev&&mode==='browser'?createHash('sha256').update(generate(ast,{compact:true,comments:false}).code).digest('hex'):undefined;
   let changed = false;
+  let ordinal=0;
   traverse(ast, {
     CallExpression(call) {
       let callee = call.get('callee');
@@ -105,6 +107,10 @@ function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
       const generated = t.objectProperty(t.identifier('loadableGenerated'), t.objectExpression([
         t.objectProperty(t.identifier('modules'), t.arrayExpression(ids.map(id => t.stringLiteral(id)))),
       ]));
+      const statement=call.findParent(value=>value.isStatement());
+      const declaration=statement?.parentPath?.isExportNamedDeclaration()?statement.parentPath:statement;
+      const stableModuleCall=call.scope===call.scope.getProgramParent()&&declaration?.parentPath?.isProgram()&&!t.isLoop(declaration.node);
+      const identity=developmentRevision&&stableModuleCall?t.objectProperty(t.identifier('__prnextDevIdentity'),t.stringLiteral(createHash('sha256').update(relative+'\0'+ordinal+++'\0'+developmentRevision).digest('hex').slice(0,24))):undefined;
 
       if (noSSR && mode !== 'browser') {
         const empty = t.arrowFunctionExpression([], t.nullLiteral(), true);
@@ -115,9 +121,10 @@ function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
         loader.replaceWith(t.arrowFunctionExpression([], loader.node));
       }
       const target = secondOptions || firstOptions;
-      if (target?.isObjectExpression()) target.node.properties.push(generated);
-      else if (target?.node) target.replaceWith(t.objectExpression([t.spreadElement(target.node), generated]));
-      else call.node.arguments.push(t.objectExpression([generated]));
+      const fields=[generated,...(identity?[identity]:[])];
+      if (target?.isObjectExpression()) target.node.properties.push(...fields);
+      else if (target?.node) target.replaceWith(t.objectExpression([t.spreadElement(target.node), ...fields]));
+      else call.node.arguments.push(t.objectExpression(fields));
       changed = true;
     },
   });

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 = [];

package/build/framework-imports.mjs

@@ -4,6 +4,7 @@ import {readFile} from 'node:fs/promises';
 import {analyzeSource} from './source-analysis.mjs';
 import {cachedTransform} from './transform-cache.mjs';
 const adapters = new Map([
+  ['cache/redis','redis-cache'],
   ['dist/shared/lib/router-context.shared-runtime','next-router-context'],
   ['dist/shared/lib/router-context','next-router-context'],
   ['dist/shared/lib/app-router-context.shared-runtime','next-app-router-context'],
@@ -23,33 +24,42 @@ export function frameworkImportName(specifier) {
 
 // Application graphs must not traverse the programmatic build API's native tools.
 // Outside a compiled application, the package root retains its full Node API.
-export function applicationEntry(builder,readSource=(file,override)=>override??readFile(file,'utf8')){
-  // esbuild understands .mts/.cts, but our framework transforms do not. Never
+export function applicationEntry(builder,readSource=(file,override)=>override??readFile(file,'utf8'),{transformTypedHelpers=false}={}){
+  // Server/client module boundaries in .mts/.cts are not supported. Never
   // silently bundle a server implementation or misclassify a client boundary.
   builder.onLoad({filter:/\.[cm]ts$/i,namespace:'file'},async args=>{
     // Loader bridges dispatch framework callbacks independently of their filters.
     if(!/\.[cm]ts$/i.test(args.path))return;
     const source=await readSource(args.path,args.prnextSource);
     const original=args.prnextSource===undefined?source:await readSource(args.path);
+    let nativeDecorators=false;
     // A loader may remove a directive as well as introduce one. Both versions
     // must be safe before its output can become an ordinary browser module.
     for(const candidate of new Set([original,source])){
-     const unsupported=cachedTransform('unsupported-framework-directives',candidate,[args.path,'v3'],()=>{
+     const unsupported=cachedTransform('unsupported-framework-directives',candidate,[args.path,'v4-native-decorators'],()=>{
       const analysis=analyzeSource(candidate,args.path);
       if(analysis.frameworkBoundary)return 'yes';
-      const pending=[analysis.program];
+      const pending=[analysis.program];let decorators=false;
       while(pending.length){
         const node=pending.pop();
         if(node.type==='ExpressionStatement'&&node.directive==='use server')return 'yes';
+        if(node.type==='Decorator'||node.decorators?.length)decorators=true;
         for(const value of Object.values(node)){
           if(Array.isArray(value)){for(const item of value)if(item?.type)pending.push(item);}
           else if(value&&typeof value==='object'&&value.type)pending.push(value);
         }
       }
-      return 'no';
+      return decorators?'decorated':'no';
      });
      if(unsupported==='yes')throw new Error(`React server/client directives are not supported in ${args.path}. Rename this file to .ts or .tsx.`);
+     nativeDecorators ||= unsupported==='decorated';
     }
+    // Compiler-enabled render graphs can transform ordinary typed helpers after
+    // this boundary check. Other consumers keep the historical esbuild path.
+    // Decorated typed helpers already have a native esbuild implementation.
+    // Keep that path instead of widening the syntax accepted by every Babel
+    // transform, while their importing React components can still be compiled.
+    if(transformTypedHelpers && !nativeDecorators)return;
     return {contents:source,loader:args.prnextSource===undefined?'ts':'tsx',resolveDir:dirname(args.path)};
   });
   builder.onResolve({filter:/^(?:prnext|@thomas\.f\/prnext)(?:\/route(?:\.js)?)?$/},()=>

package/build/html-only-config.mjs

@@ -0,0 +1,53 @@
+import {assertHtmlOnlyDocument} from '../runtime/html-only.mjs';
+const MAX_PATTERNS = 128;
+
+export function validateHtmlOnly(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_PATTERNS) throw new TypeError('htmlOnly must be an array of at most 128 App route patterns.');
+  for (const pattern of value) {
+    if (typeof pattern !== 'string' || pattern.length > 512 || !pattern.startsWith('/') || pattern.startsWith('//') ||
+        /[\s\\?#\u0000-\u001f\u007f]/.test(pattern) || /%(?![\da-f]{2})/i.test(pattern)) throw new TypeError('htmlOnly entries must be clean absolute route patterns without queries, fragments, whitespace or backslashes.');
+    const pathname = pattern.endsWith('/**') ? pattern.slice(0, -3) || '/' : pattern;
+    if (pathname.includes('*') || (pathname !== '/' && pathname.endsWith('/')) || pathname.slice(1).includes('//')) throw new TypeError('htmlOnly supports exact registered route patterns and a final /** subtree suffix only.');
+    for (const segment of pathname.split('/').slice(1)) {
+      let decoded;
+      try { decoded = decodeURIComponent(segment); } catch { throw new TypeError('htmlOnly patterns must use valid URL encoding.'); }
+      if (decoded === '.' || decoded === '..' || /[\\/\u0000-\u001f\u007f]/.test(decoded)) throw new TypeError('htmlOnly patterns cannot contain dot segments or encoded path separators.');
+    }
+  }
+  return [...new Set(value)];
+}
+
+export function matchesHtmlOnly(pattern, routePattern) {
+  if (!pattern.endsWith('/**')) return pattern === routePattern;
+  const prefix = pattern.slice(0, -3);
+  return !prefix || routePattern === prefix || routePattern.startsWith(prefix + '/');
+}
+
+export function selectHtmlOnlyRoutes(routes, patterns, { cacheComponents = false } = {}) {
+  const selected = new Set();
+  for (const pattern of validateHtmlOnly(patterns)) {
+    const matches = routes.filter(route => !route.internal && matchesHtmlOnly(pattern, route.pattern));
+    if (!matches.length) throw new Error(`htmlOnly pattern ${JSON.stringify(pattern)} does not match a registered route.`);
+    for (const route of matches) {
+      if (route.router !== 'app' || route.kind !== 'page') throw new Error(`htmlOnly route ${route.pattern} must be an App Router page; Pages Router and Route Handlers are not supported.`);
+      const config = route.cacheConfig || {};
+      if (cacheComponents || config.runtime === 'edge' || config.dynamic === 'force-dynamic' || config.forceNoStore || (config.revalidate !== undefined && config.revalidate !== false)) {
+        throw new Error(`htmlOnly route ${route.pattern} must be fully prerendered without Edge, Cache Components/PPR, dynamic rendering or ISR.`);
+      }
+      if (route.parallel || route.interception) throw new Error(`htmlOnly route ${route.pattern} does not support parallel or intercepted routing.`);
+      if (route.pattern.includes('[') && config.dynamicParams !== false) throw new Error(`htmlOnly route ${route.pattern} requires dynamicParams: false and complete generateStaticParams results.`);
+      selected.add(route.id);
+    }
+  }
+  return selected;
+}
+
+export function validateHtmlOnlyPrerender(route, rendered) {
+  if (!route.htmlOnly) return;
+  if (rendered.dynamic || rendered.partial || rendered.revalidate !== false || (rendered.status ?? 200) !== 200) {
+    throw new Error(`htmlOnly route ${route.pattern} must produce a complete successful static HTML document without dynamic data, partial rendering, redirects or ISR.`);
+  }
+  const html = Buffer.isBuffer(rendered.body) ? rendered.body.toString('utf8') : rendered.body;
+  assertHtmlOnlyDocument(html, route.pattern);
+}

package/build/html-only-graph.mjs

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import { builtinModules } from 'node:module';
+import { analyzeSource } from './source-analysis.mjs';
+import { frameworkImportName, frameworkImportPattern } from './framework-imports.mjs';
+
+const builtins = new Set([...builtinModules, ...builtinModules.map(name => 'node:' + name)]);
+const interactive = new Set(['link','image','head','script','dynamic','router','compat/router','next-router-context','next-app-router-context']);
+const namespace = /^prnext-(?:css-mapping|compiled-css|app-empty|edge-empty):/;
+
+export function createHtmlOnlyGraph(root) {
+  const graph = new Map(), issues = new Map();
+  const file = value => path.resolve(root, value.replace(namespace, ''));
+  function issue(filename, reason) {
+    const key = file(filename);
+    if (!issues.has(key)) issues.set(key, reason);
+  }
+  return {
+    issue,
+    alias(source, target) {
+      if (file(source) !== file(target)) graph.set(file(source), [{ path:file(target) }]);
+    },
+    source(filename, source) {
+      const { program, directives, computedRequire, imports } = analyzeSource(source, filename);
+      if (directives.includes('use client')) issue(filename, 'a Client Component (use client)');
+      if (computedRequire) issue(filename, 'a computed require() whose dependencies cannot be validated');
+      for (const dependency of imports) if (frameworkImportPattern.test(dependency.path) && interactive.has(frameworkImportName(dependency.path))) issue(filename, `interactive framework import ${dependency.path}; use ordinary HTML elements instead`);
+      const pending = [program];
+      while (pending.length) {
+        const node = pending.pop();
+        if (node.directive === 'use server') issue(filename, 'a Server Action (use server)');
+        if (node.type === 'ImportExpression' && typeof node.source?.value !== 'string') issue(filename, 'a computed import() whose dependencies cannot be validated');
+        if (node.type === 'JSXOpeningElement' && node.name?.type === 'JSXIdentifier' && ['script','iframe','object','embed'].includes(node.name.name.toLowerCase())) issue(filename, `a <${node.name.name}> element`);
+        if (node.type === 'JSXAttribute' && node.name?.type === 'JSXIdentifier' && /^on[A-Z]/.test(node.name.name)) issue(filename, `interactive event property ${node.name.name}`);
+        for (const value of Object.values(node)) {
+          if (Array.isArray(value)) { for (const child of value) if (child?.type) pending.push(child); }
+          else if (value && typeof value === 'object' && value.type) pending.push(value);
+        }
+      }
+    },
+    record(metafile) {
+      for (const [name, input] of Object.entries(metafile?.inputs || {})) {
+        const key=file(name), dependencies=graph.get(key) || [];
+        for (const dependency of input.imports || []) {
+          if (!dependency.external) dependencies.push({path:file(dependency.path)});
+          else if (!builtins.has(dependency.path) && !/^(?:react|react-dom|react-server-dom-webpack)(?:\/|$)/.test(dependency.path) && !/^\.\.\/compat\/(?:navigation|headers|cache|server|font-local|font-google|og)\.cjs$/.test(dependency.path)) {
+            dependencies.push({external:dependency.path});
+          }
+        }
+        graph.set(key,dependencies);
+      }
+    },
+    validate(route) {
+      const roots = new Set([route.file, ...Object.values(route.segments || {}).flatMap(segment => Object.values(segment).filter(value => typeof value === 'string' && /\.[cm]?[jt]sx?$/.test(value))), ...(route.metadataFiles || []).map(item => item.file)].filter(Boolean));
+      const pending=[...roots].map(file), seen=new Set();
+      while (pending.length) {
+        const current=pending.pop();
+        if (seen.has(current)) continue;
+        seen.add(current);
+        if (issues.has(current)) throw new Error(`htmlOnly route ${route.pattern} reaches ${issues.get(current)} in ${path.relative(root,current)}.`);
+        for (const dependency of graph.get(current) || []) {
+          if (dependency.external) throw new Error(`htmlOnly route ${route.pattern} reaches unverified external dependency ${dependency.external} from ${path.relative(root,current)}. Bundle a static server dependency or remove it from this HTML-only route.`);
+          pending.push(dependency.path);
+        }
+      }
+    },
+  };
+}