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

package/cli.mjs

@@ -1,23 +1,27 @@
 #!/usr/bin/env node
-import { rename } from './runtime/fs.mjs';
 import { spawn } from 'node:child_process';
-import { readFile, writeFile, rm, mkdir, readdir } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
+import { readFile, rm, mkdir, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveNativeBinary, packageManifest } from './native/resolve.mjs';
 import { replaceWithNative } from './native/launch.mjs';
 import { readBuildDirectory } from './runtime/build-directory.mjs';
-import { shouldWatchProjectFile } from './runtime/env.mjs';
 
-const self = fileURLToPath(import.meta.url);
 const [command = 'help', ...argv] = process.argv.slice(2);
 const help = `PRNext ${packageManifest.version}
 
 Use prnext for portable scripts; prn is a shortcut on compatible shells.
 
+  prnext create <directory>            Create a project and install dependencies
+  prnext create <directory> --no-install  Prepare project files without installing
+  prnext create --help                 TypeScript, JavaScript and creation options
   prnext build [directory]              Build React/TypeScript and static HTML
+  prnext build [directory] --watch      Incremental production rebuilds on changes
   prnext build [directory] --adapter static [--from dist] [--spa]
                                        Import an existing public build directory
+  prnext build [directory] --adapter auto
+                                       Detect a completed browser build
+  prnext build [directory] --adapter static --from .
+                                       Build a plain HTML/CSS/JS site
   prnext output [directory] [--json]    Read the versioned build output contract
   prnext start [directory] [options]    Start native Rust production server
   prnext pstart [directory] [options]   Start production persistently in the background
@@ -28,9 +32,18 @@ Use prnext for portable scripts; prn is a shortcut on compatible shells.
   prnext pstartup [--remove]            Configure restoration at user login
   prnext pstart --help                  All persistent commands and options
   prnext dev [directory] [options]      Rebuild and restart on source changes
+  prnext dev [directory] --host-ai      Share local diagnostics with your connected Host AI
+  prnext dev [directory] --safe         Use full builds and fresh workers for troubleshooting
+  prnext mcp [directory]                Connect an AI to the running local dev server
+  prnext docs --ai [topic]              Read the AI guide bundled with this version
+  prnext docs --ai --init [directory]   Add a guide pointer to the project's AGENTS.md
   prnext routes [directory]             Display compiled routes
-  prnext check [directory] [--json]      Check an existing Next project before building
+  prnext check [directory] [--json]      Diagnose config, routes, Node, native and dependencies
+  prnext typegen [directory] [--json]    Generate route types without building the app
+  prnext typecheck [directory] [--json]  Generate types and check TypeScript without building
   prnext inspect [directory] [--json|--otlp] Explain routes, health and sampled timings
+  prnext analyze [directory] [--json] [--max-js 150]  Browser bundles and budget (kB)
+  prnext compiler [directory] [--json]  React Compiler results from the last successful build
   prnext host [prnext.host.json]         Host built apps by hostname; wake on demand
   prnext host [config] --check           Validate hosting configuration and builds
   prnext host [config] --status [--json]  Show memory, process and idle status
@@ -47,9 +60,25 @@ Migration options: --dry-run (preview), --no-install (prepare only), --json
                                        Compare GET responses before switching
 Migration keeps Next.js and backs up package.json and existing lockfiles.
 Simple next dev/build/start scripts become prnext commands; custom shell scripts need a manual edit.
+Installation honors npm, pnpm, Yarn Classic/Berry and the workspace root.
+The preview reports the manager, root and selected workspace. Failed installs
+restore the selected manifest/lockfiles; dependency caches may need a retry.
+
+Type commands require an application tsconfig and TypeScript installation.
+They generate route types unless typedRoutes: false, preserve JSONC/extends,
+and report updates to tsconfig/prnext-env.d.ts. typecheck always checks errors.
+
+Analysis options: --metric raw|gzip|brotli (default raw), --baseline analysis.json
+  --max-js 150                         Maximum initial JS per route, in kB
+  --max-increase-bytes 1024 --max-increase-percent 5
+  --budgets budgets.json               Exact route keys with maxJs (kB),
+                                       maxIncreaseBytes and/or maxIncreasePercent
+Analysis exit codes: 0 passed, 1 budget exceeded or initial total unverifiable,
+  2 invalid input or missing build. Request-dependent totals are lower bounds.
 
 Server options: --port 3000 --hostname 127.0.0.1 --workers 1 --inspect
 Production profiles: --profile balanced|speed|memory|classic
+Render readiness: --prewarm --readiness-file /private/path/ready.json
 Worker retirement: --worker-idle-seconds 300 --lane-idle-seconds 30 --keep-warm [true|false]
 Memory favors lower RAM under concurrency, accepting more waiting and CPU per response.
 Without an option: PRNEXT_PROFILE, legacy PRNEXT_MEMORY_PROFILE=compact, then balanced.
@@ -78,6 +107,42 @@ function stop(child) {
 async function main() {
   if (['help', '--help', '-h'].includes(command)) { console.log(help); return; }
   if (['--version', '-v'].includes(command)) { console.log(packageManifest.version); return; }
+  if (command === 'create') {
+    const { createHelp, parseCreateArgs, createProject } = await import('./build/create.mjs');
+    if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) { console.log(createHelp); return; }
+    const { directory, options } = parseCreateArgs(argv);
+    const controller = new AbortController();
+    let interrupted;
+    const interrupt = signal => { interrupted = signal; controller.abort(); };
+    const onInt = () => interrupt('SIGINT'), onTerm = () => interrupt('SIGTERM');
+    process.on('SIGINT', onInt); process.on('SIGTERM', onTerm);
+    try {
+      const report = await createProject(directory, { ...options, signal: controller.signal,
+        onOutput: options.json ? () => {} : (chunk, stream) => process[stream].write(chunk) });
+      if (options.json) console.log(JSON.stringify(report, null, 2));
+      else {
+        console.log(`PRNext project ${report.status}: ${report.root}`);
+        if (report.error) console.error(report.error);
+        if (!report.ok) console.log('Project files were preserved. Retry installation from this directory.');
+        if (path.resolve(process.cwd()) !== directory) console.log(`\nOpen ${report.root} in your terminal, then run:`);
+        for (const next of report.next) console.log(`  ${next}`);
+      }
+      if (!report.ok) process.exitCode = interrupted === 'SIGINT' ? 130 : interrupted === 'SIGTERM' ? 143 : 1;
+    } finally { process.removeListener('SIGINT', onInt); process.removeListener('SIGTERM', onTerm); }
+    return;
+  }
+  if (command === 'docs') {
+    const { executeAiDocs } = await import('./runtime/ai-docs.mjs');
+    const result = await executeAiDocs(argv);
+    process.stdout.write(result.output);
+    return;
+  }
+  if (command === 'mcp') {
+    if (argv.includes('--help') || argv.includes('-h')) { console.log('prnext mcp [directory]\nLocal development MCP over stdio. Start prnext dev first; no shell or production access is exposed.'); return; }
+    if (argv.length > 1 || argv.some(arg => arg.startsWith('-'))) throw Error('mcp accepts only [directory]');
+    const {runDevMcp}=await import('./runtime/dev-tools-mcp.mjs');
+    await runDevMcp(path.resolve(argv[0] || '.'));return;
+  }
   if (['login', 'logout', 'whoami', 'deploy', 'update'].includes(command)) {
     const { cloudCommand } = await import('./runtime/cloud/client.mjs');
     await cloudCommand(command, argv);
@@ -150,9 +215,59 @@ async function main() {
     if (!report.ok) process.exitCode = 1;
     return;
   }
-  if (!['build', 'start', 'dev', 'routes', 'check', 'inspect', 'output'].includes(command)) throw new Error(`Unknown command: ${command}\n${help}`);
+  if (!['build', 'start', 'dev', 'routes', 'check', 'typegen', 'typecheck', 'inspect', 'analyze', 'compiler', 'output'].includes(command)) throw new Error(`Unknown command: ${command}\n${help}`);
   const args = [...argv];
   const root = path.resolve(args[0] && !args[0].startsWith('-') ? args.shift() : '.');
+  if (['check','typegen','typecheck','analyze','compiler'].includes(command) && args.some(arg => ['--help','-h'].includes(arg))) { console.log(help); return; }
+  if(command==='compiler'){
+    try {
+      if(args.some(arg=>arg!=='--json') || args.filter(arg=>arg==='--json').length>1)throw new Error('compiler accepts only [directory] and --json');
+      const {readReactCompilerReport,printReactCompilerReport}=await import('./build/react-compiler-report.mjs');
+      const {readBuildOutput}=await import('./build/output-contract.mjs');
+      const directory=path.join(root,await readBuildDirectory(root));
+      const output=await readBuildOutput(directory);
+      if(output.adapter!=='react')throw new Error('React Compiler reports apply to React builds. This application uses the static adapter.');
+      const report=await readReactCompilerReport(directory,{buildId:output.buildId});
+      if(!report)throw new Error('No React Compiler report is available. Rebuild this application with the installed PRNext version.');
+      if(args.includes('--json'))console.log(JSON.stringify(report,null,2));else printReactCompilerReport(report,{details:true});
+    } catch(error) {
+      if(args.includes('--json'))console.log(JSON.stringify({ok:false,error:error.message}));
+      else console.error(`PRNext compiler: ${error.message}`);
+      process.exitCode=2;
+    }
+    return;
+  }
+  if(command==='analyze'){
+    try {
+      const {analyzeBuild,printAnalysis,parseAnalysisArgs}=await import('./build/analyze.mjs');
+      const options=parseAnalysisArgs(args),report=await analyzeBuild(root,options);
+      if(options.json)console.log(JSON.stringify(report,null,2));else printAnalysis(report);
+      if(!report.ok)process.exitCode=1;
+    } catch(error) {
+      if(args.includes('--json'))console.log(JSON.stringify({ok:false,error:error.message}));
+      else console.error(`PRNext analysis: ${error.message}`);
+      process.exitCode=2;
+    }
+    return;
+  }
+  if (command === 'typegen' || command === 'typecheck') {
+    if (args.some(arg => arg !== '--json') || args.filter(arg => arg === '--json').length > 1) throw new Error(`${command} accepts only [directory] and --json`);
+    const { runTypeCommand } = await import('./build/type-command.mjs');
+    process.chdir(root);
+    process.env.INIT_CWD = root;
+    process.env.PWD = root;
+    const report = await runTypeCommand(root, { check: command === 'typecheck' });
+    if (args.includes('--json')) console.log(JSON.stringify(report, null, 2));
+    else {
+      console.log(`PRNext ${command} ${report.ok ? 'passed' : 'failed'}: ${root}`);
+      console.log(`${report.routes} page routes; tsconfig: ${report.tsconfig || 'unavailable'}; route types: ${report.typedRoutes ? 'enabled' : 'disabled'}.`);
+      for (const file of report.updated) console.log(`Updated ${file}`);
+      for (const note of report.notes) console.log(note);
+      for (const error of report.errors) console.error(error);
+    }
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
   if (command === 'output') {
     if (args.some(arg => arg !== '--json')) throw new Error('output accepts only [directory] and --json');
     const { readBuildOutput } = await import('./build/output-contract.mjs');
@@ -196,7 +311,10 @@ async function main() {
     else {
       console.log(`PRNext preflight ${report.ok ? 'passed' : 'failed'}: ${root}`);
       console.log(`${report.routes.length} routes. Installed versions: ${Object.entries(report.versions).map(([name,version])=>`${name}@${version||'missing'}`).join(', ')}`);
-      for (const error of report.errors) console.error(error);
+      for (const item of report.diagnostics) {
+        const output = item.severity === 'error' ? console.error : console.log;
+        output(`${item.severity}: ${item.message}${item.action ? ` ${item.action}` : ''}`);
+      }
       for (const note of report.notes) console.log(note);
     }
     if (!report.ok) process.exitCode = 1;
@@ -207,6 +325,7 @@ async function main() {
     for (let i = 0; i < args.length; i++) {
       const flag = args[i];
       if (flag === '--dev') options.dev = true;
+      else if (flag === '--watch') options.watch = true;
       else if (flag === '--spa') options.spa = true;
       else if (flag === '--adapter' || flag === '--from') {
         const value = args[++i];
@@ -220,131 +339,52 @@ async function main() {
     const envMode = process.env.NODE_ENV === 'test' ? 'test' : undefined;
     process.env.NODE_ENV = dev ? 'development' : 'production';
     const started = performance.now();
+    if(options.watch){
+      if(dev)throw new Error('--watch builds production; use prnext dev for development.');
+      const {watchProduction}=await import('./build/production-builder.mjs');
+      delete options.watch;await watchProduction(root,options);return;
+    }
+    if (options.adapter === undefined || options.adapter === 'auto') {
+      const { detectBuildAdapter } = await import('./build/static-input.mjs');
+      const selected = await detectBuildAdapter(root, { prepared: options.adapter === 'auto' });
+      if (selected.adapter === 'static') Object.assign(options, selected);
+      else if (options.adapter === 'auto') options.adapter = 'react';
+    }
     if (options.adapter === 'static') {
       const { buildStatic } = await import('./build/static-adapter.mjs');
       await buildStatic(root, options);
     } else {
       const { build } = await import('./build/index.mjs');
-      await build(root, { ...options, dev, envMode });
+      const result=await build(root, { ...options, dev, envMode });
+      if(!dev&&result.compilationCache?.hits){
+        const {hits,reusedBytes}=result.compilationCache;
+        console.log(`Compilation cache: ${hits} ${hits===1?'graph':'graphs'} reused (${Math.ceil(reusedBytes/1024)} KiB).`);
+      }
+      if(result.reactCompilerReport?.enabled){
+        const {printReactCompilerReport}=await import('./build/react-compiler-report.mjs');
+        printReactCompilerReport(result.reactCompilerReport,{details:false});
+      }
     }
     console.log(`PRNext built ${root} in ${((performance.now() - started) / 1000).toFixed(2)}s`);
     return;
   }
   const binary = await resolveNativeBinary();
-  let outputDirectory = await readBuildDirectory(root);
-  const serverEnvironment = { ...process.env, NODE_ENV: process.env.NODE_ENV || (command === 'dev' ? 'development' : 'production') };
-  if (command === 'start' && serverEnvironment.NODE_ENV !== 'development') {
-    if (replaceWithNative(binary, ['start', root, '--worker', path.join(root, outputDirectory, 'runtime/worker.mjs'),
-      '--node', process.execPath, ...args], serverEnvironment)) return;
-  }
-  const launch = () => spawn(binary, [command === 'routes' ? 'routes' : 'start', root,
-    ...(command === 'routes' ? [] : ['--worker', path.join(root, outputDirectory, 'runtime/worker.mjs'), '--node', process.execPath,
-      '--shutdown-on-stdin-eof']), ...args], { stdio: ['pipe', 'inherit', 'inherit'], windowsHide: true, env: { ...process.env, NODE_ENV: process.env.NODE_ENV || (command === 'dev' ? 'development' : 'production') } });
-  let server;
-  let stopping = false;
-  let watcher;
-  let rebuildChild;
-  let timer;
-  const devStateFile = path.join(root, '.prnext-dev.json');
-  const changedFiles = new Set();
-  async function notifyDev(value) {
-    const temporary = `${devStateFile}.${process.pid}.tmp`;
-    await writeFile(temporary, JSON.stringify(value));
-    await rename(temporary, devStateFile);
+  if(command==='dev') {const {develop}=await import('./runtime/development.mjs');await develop(root,args,binary);return;}
+  const outputDirectory = await readBuildDirectory(root);
+  const serverEnvironment = {...process.env,NODE_ENV:process.env.NODE_ENV||'production'};
+  if(command==='start'&&serverEnvironment.NODE_ENV!=='development'){
+    if(replaceWithNative(binary,['start',root,'--worker',path.join(root,outputDirectory,'runtime/worker.mjs'),
+      '--node',process.execPath,...args],serverEnvironment))return;
   }
-  const shutdown = async () => {
-    if (stopping) return;
-    stopping = true;
-    clearTimeout(timer);
-    watcher?.close();
-    await Promise.all([stop(server), stop(rebuildChild)]);
-    if (command === 'dev') await rm(devStateFile, { force: true });
-  };
-  process.once('SIGINT', shutdown);
-  process.once('SIGTERM', shutdown);
-  if (command !== 'dev') {
-    server = launch();
-    await done(server).catch(error => { if (!stopping) throw error; });
-    return;
-  }
-  let building = false;
-  let queued = false;
-  let attempted = false;
-  const {createDevChangeFilter} = await import('./runtime/dev-file-changes.mjs');
-  const filterChanges = createDevChangeFilter(root);
-  async function rebuild() {
-    if (stopping) return;
-    if (building) { queued = true; return; }
-    building = true;
-    const pending = [...changedFiles];
-    changedFiles.clear();
-    let buildOutput = '';
-    try {
-      const actualChanges = await filterChanges(pending);
-      if (stopping) return;
-      if (attempted && !actualChanges.length) return;
-      attempted = true;
-      const changed = actualChanges.slice(0, 32).map(file => file.slice(0, 256));
-      await notifyDev({ state: 'building' });
-      if (actualChanges.some(file => /(?:^|\/)(?:(?:next|prnext|contentlayer)\.config\.|package(?:-lock)?\.json$|(?:pnpm-lock\.yaml|yarn\.lock)$)/.test(file))) { await stop(rebuildChild); rebuildChild = undefined; }
-      if (stopping) return;
-      if (!rebuildChild || rebuildChild.exitCode !== null || rebuildChild.signalCode) {
-        rebuildChild = spawn(process.execPath, [path.join(path.dirname(self), 'build/dev-worker.mjs')], { stdio: ['inherit', 'pipe', 'pipe', 'ipc'], env: { ...process.env, NODE_ENV: process.env.NODE_ENV || 'development' } });
-      }
-      const stdout = chunk => { process.stdout.write(chunk); buildOutput = (buildOutput + chunk).slice(-12_000); };
-      const stderr = chunk => { process.stderr.write(chunk); buildOutput = (buildOutput + chunk).slice(-12_000); };
-      rebuildChild.stdout.on('data', stdout); rebuildChild.stderr.on('data', stderr);
-      let result;
-      try {
-        result = await new Promise((resolve, reject) => {
-          const worker = rebuildChild;
-          const cleanup = () => { worker.off('message', message); worker.off('exit', exited); worker.off('error', failed); };
-          const message = value => { if (value?.type === 'result') { cleanup(); resolve(value); } };
-          const exited = (code, signal) => { cleanup(); reject(new Error(`Compiler exited ${signal || code}`)); };
-          const failed = error => { cleanup(); reject(error); };
-          worker.on('message', message); worker.once('exit', exited); worker.once('error', failed);
-          worker.send({type:'build',root});
-        });
-      } finally { rebuildChild.stdout.off('data', stdout); rebuildChild.stderr.off('data', stderr); }
-      if (result.recycle) { await stop(rebuildChild); rebuildChild = undefined; }
-      if (!result.ok) throw new Error(result.error);
-      filterChanges.acceptInputs(result.inputs || []);
-      if (!stopping) {
-        await stop(server);
-        outputDirectory = await readBuildDirectory(root);
-        await watcher.refresh();
-        // Shutdown can arrive while the previous server is draining. Never
-        // leave a replacement running after shutdown already stopped its peers.
-        if (stopping) return;
-        for (const file of changedFiles) {
-          if (file === outputDirectory || file.startsWith(outputDirectory + '/') || outputDirectory.startsWith(file + '/')) changedFiles.delete(file);
-        }
-        if (!changedFiles.size) { clearTimeout(timer); queued = false; }
-        server = launch();
-        server.on('error', error => console.error(`PRNext server: ${error.message}`));
-        const manifest = JSON.parse(await readFile(path.join(root, outputDirectory, 'manifest.json'), 'utf8'));
-        if (stopping) return;
-        await notifyDev({ state: 'ready', buildId: manifest.buildId, clientManifest: manifest.devClient, changed });
-        console.log('Source compiled. React Fast Refresh applied in connected browsers.');
-      }
-    } catch (error) { if (!stopping) { console.error(`Build failed: ${error.message}`); await notifyDev({ state: 'error', error: buildOutput || error.message }); } }
-    finally { building = false; if (queued && !stopping) { queued = false; void rebuild(); } }
-  }
-  const { watchProject } = await import('./runtime/watch-project.mjs');
-  watcher = await watchProject(root, {
-    ignore: relative => relative === outputDirectory || relative.startsWith(outputDirectory + '/'),
-    onError: error => { console.error(`PRNext development watcher: ${error.message}`); process.exitCode = 1; void shutdown(); },
-    onChange: filename => {
-    if (stopping) return;
-    const relative = String(filename || '').replaceAll(path.sep, '/');
-    if (relative === outputDirectory || relative.startsWith(outputDirectory + '/') || !shouldWatchProjectFile(filename)) return;
-    changedFiles.add(String(filename).replaceAll(path.sep, '/'));
-    clearTimeout(timer);
-    timer = setTimeout(() => { if (changedFiles.size) void rebuild(); }, 150);
-    },
-  });
-  if (stopping) { watcher.close(); return; }
-  await rebuild();
+  const server=spawn(binary,[command==='routes'?'routes':'start',root,
+    ...(command==='routes'?[]:['--worker',path.join(root,outputDirectory,'runtime/worker.mjs'),'--node',process.execPath,'--shutdown-on-stdin-eof']),...args],
+    {stdio:['pipe','inherit','inherit'],windowsHide:true,env:serverEnvironment});
+  let stopping=false;
+  const shutdown=async()=>{if(stopping)return;stopping=true;await stop(server);};
+  process.once('SIGINT',shutdown);process.once('SIGTERM',shutdown);
+  try{await done(server).catch(error=>{if(!stopping)throw error;});}
+  finally{process.off('SIGINT',shutdown);process.off('SIGTERM',shutdown);await stop(server);}
+
 }
 
 main().catch(error => { console.error(`PRNext: ${error.message}`); process.exitCode = 1; });

package/compat/activity-cache.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+// A shared budget across layout slots, rather than a separate page budget at
+// every nesting level. Only inactive branches enter this registry.
+function createActivityCache({ limit = 4, ttl = 120000, now = Date.now, schedule = setTimeout, cancel = clearTimeout } = {}) {
+  const entries = new Map(); let timer;
+  function arm() {
+    cancel(timer); timer = undefined;
+    if (entries.size) {
+      timer = schedule(prune, Math.max(1, Math.min(...[...entries.values()].map(entry => entry.expires)) - now()));
+      timer?.unref?.();
+    }
+  }
+  function prune() {
+    for (const [key, entry] of entries) if (entry.expires <= now()) { entries.delete(key); entry.evict(); }
+    while (entries.size > limit) { const [key, entry] = entries.entries().next().value; entries.delete(key); entry.evict(); }
+    arm();
+  }
+  return {
+    retain(key, evict) { if (!entries.has(key)) entries.set(key, { evict, expires: now() + ttl }); prune(); },
+    release(key) { entries.delete(key); arm(); },
+    clear() { const previous = [...entries.values()]; entries.clear(); cancel(timer); timer = undefined; for (const entry of previous) entry.evict(); },
+    get size() { return entries.size; },
+  };
+}
+module.exports = { createActivityCache };

package/compat/after.cjs

@@ -4,11 +4,11 @@ const { AsyncLocalStorage } = require('node:async_hooks');
 function after(task) {
   const context = require('./headers.cjs').currentRequest();
   if (require('./data-cache.cjs').inCacheScope()) throw new Error('after() cannot be registered inside a cache scope');
-  if (!context.afterScope || !['route', 'action', 'after'].includes(context.phase)) throw new Error('after() currently requires a Node Route Handler or Server Action in PRNext. Server Component and Edge after() lifecycles are not implemented.');
+  if (!context.afterScope || !['route', 'action', 'render', 'after'].includes(context.phase)) throw new Error('after() requires a Node Server Component, Route Handler or Server Action. Edge after() is not implemented.');
   context.afterScope.add(task, context, AsyncLocalStorage.snapshot());
 }
 
-function createAfterScope({ signal, timeoutMs = 25000, onTimeout = () => {}, onComplete, report = error => console.error('[prnext] after() failed:', error?.stack || error) } = {}) {
+function createAfterScope({ signal, timeoutMs = 25000, onTimeout = () => {}, onComplete, onRegistered, report = error => console.error('[prnext] after() failed:', error?.stack || error) } = {}) {
   const queue = []; let count = 0, closed = false, finishing;
   const deadline = Date.now() + timeoutMs;
   const track = promise => signal?.[Symbol.for('prnext.request-work')]?.(promise, { timeoutMs: Math.max(1, deadline - Date.now()) });
@@ -18,6 +18,7 @@ function createAfterScope({ signal, timeoutMs = 25000, onTimeout = () => {}, onC
       if (closed) throw new Error('after() request has already completed');
       if (typeof task !== 'function' && (!task || typeof task.then !== 'function')) throw new TypeError('after() expects a callback or a Promise');
       if (++count > 128) throw new Error('after() exceeds 128 tasks per request');
+      if (count === 1) onRegistered?.();
       const pending = typeof task === 'function' ? null : observe(task);
       if (pending) track(pending);
       queue.push({ task: pending ? null : task, pending, context, run });
@@ -27,8 +28,9 @@ function createAfterScope({ signal, timeoutMs = 25000, onTimeout = () => {}, onC
         try {
           while (queue.length) {
             const item = queue.shift(), remaining = deadline - Date.now();
-            if (remaining <= 0) { const error = new Error('after() exceeded the request maxDuration'); report(error); onTimeout(error); break; }
+            if (remaining <= 0) { const error = new Error('after() exceeded the request maxDuration'); await item.run(()=>report(error)); onTimeout(error); break; }
             const abort = new AbortController();
+            item.context.afterRestricted ||= item.context.phase === 'render';
             item.context.cookies._mutable = false;
             item.context.phase = 'after';
             item.context.signal = abort.signal;
@@ -38,7 +40,7 @@ function createAfterScope({ signal, timeoutMs = 25000, onTimeout = () => {}, onC
             let timer;
             try {
               const outcome = await Promise.race([work, new Promise(resolve => { timer = setTimeout(() => { const error = new Error('after() exceeded the request maxDuration'); abort.abort(error); resolve({ error }); }, remaining); })]);
-              if ('error' in outcome) report(outcome.error);
+              if ('error' in outcome) await item.run(()=>report(outcome.error));
               if (abort.signal.aborted) { onTimeout(outcome.error); break; }
             } finally { clearTimeout(timer); item.context.cacheState.closed = true; await onComplete?.(item.context); }
           }

package/compat/app-layout-context.cjs

@@ -1,8 +1,53 @@
 'use client';
 'use strict';
 const React = require('react');
+const { AppRouterContext } = require('./app-context.cjs');
 const LayoutContext = React.createContext({ children: [] });
 const LayoutCacheContext = React.createContext(null);
+const ActivityCacheContext = React.createContext(null);
+
+function ActivitySlot({ identity, children, authorizationKey }) {
+  const retention = React.useContext(ActivityCacheContext);
+  authorizationKey ??= retention?.authorizationKey;
+  const router = React.useContext(AppRouterContext);
+  const epoch = retention?.epoch ?? 0;
+  const authorizationEpoch = retention?.authorizationEpoch ?? 0;
+  const registrations = React.useRef(new Set());
+  const serial = React.useRef(0);
+  const [saved, setSaved] = React.useState(() => ({ epoch, authorizationEpoch, active: identity, entries: new Map() }));
+  let entries = saved.entries;
+  const current = entries.get(identity);
+  if (saved.epoch !== epoch || saved.authorizationEpoch !== authorizationEpoch || current?.children !== children || current?.router !== router || current?.authorizationKey !== authorizationKey) {
+    const sameAuthorization = saved.authorizationEpoch === authorizationEpoch && !(current?.authorizationKey && authorizationKey && current.authorizationKey !== authorizationKey);
+    entries = saved.epoch === epoch && sameAuthorization ? new Map(entries) : new Map();
+    const preserve = current && saved.authorizationEpoch === authorizationEpoch && (sameAuthorization && (saved.epoch === epoch || saved.active === identity)
+      || !retention?.strictAuthorization && saved.active === identity);
+    entries.set(identity, { children, router, authorizationKey, token: preserve ? current.token : {}, reactKey: preserve ? current.reactKey : ++serial.current });
+    setSaved({ epoch, authorizationEpoch, active: identity, entries });
+  }
+  React.useLayoutEffect(() => {
+    const cache = retention?.cache;
+    if (!cache) return;
+    const inactive = new Set([...entries].filter(([key]) => key !== identity).map(([, entry]) => entry.token));
+    for (const token of registrations.current) if (!inactive.has(token)) cache.release(token);
+    for (const [key, entry] of entries) {
+      if (key === identity) cache.release(entry.token);
+      else cache.retain(entry.token, () => setSaved(previous => {
+        if (!previous.entries.has(key)) return previous;
+        const next = new Map(previous.entries); next.delete(key); return { ...previous, entries: next };
+      }));
+    }
+    registrations.current = inactive;
+  }, [entries, identity, retention?.cache]);
+  React.useLayoutEffect(() => () => {
+    for (const token of registrations.current) retention?.cache.release(token);
+    registrations.current.clear();
+  }, [retention?.cache]);
+  // Identical boundary structure during SSR and hydration. Hidden branches get
+  // their original router context and their effects are disconnected by React.
+  return [...entries].map(([key, entry]) => React.createElement(React.Activity, { key: entry.reactKey, mode: key === identity ? 'visible' : 'hidden' },
+    React.createElement(AppRouterContext.Provider, { value: key === identity ? router : entry.router }, entry.children)));
+}
 
 function LayoutProvider({ id, segments, children }) {
   const cache = React.useContext(LayoutCacheContext);
@@ -13,15 +58,20 @@ function LayoutProvider({ id, segments, children }) {
   return React.createElement(LayoutContext.Provider, { value: current }, children);
 }
 
-function LayoutSlot({ id, preserve, children }) {
+function LayoutSlot({ id, preserve, children, activityKey, activityPreserve, authorizationKey }) {
   const cache = React.useContext(LayoutCacheContext);
   const previous = React.useRef(children);
   const current = preserve && cache && Object.hasOwn(cache.slots, id) ? cache.slots[id] : preserve ? previous.current : children;
   React.useLayoutEffect(() => { previous.current = current; if (cache && id) cache.slots[id] = current; }, [cache, id, current]);
-  return current ?? null;
+  const previousKey = React.useRef(activityKey);
+  const identity = preserve || activityPreserve ? previousKey.current : activityKey;
+  React.useLayoutEffect(() => { previousKey.current = identity; }, [identity]);
+  return activityKey === undefined ? current ?? null : React.createElement(ActivitySlot, { identity, authorizationKey }, current);
 }
 
 module.exports.LayoutContext = LayoutContext;
 module.exports.LayoutCacheContext = LayoutCacheContext;
 module.exports.LayoutProvider = LayoutProvider;
 module.exports.LayoutSlot = LayoutSlot;
+module.exports.ActivitySlot = ActivitySlot;
+module.exports.ActivityCacheContext = ActivityCacheContext;

package/compat/base64.cjs

@@ -0,0 +1,10 @@
+'use strict';
+// Native decoding avoids a JavaScript callback for each Flight byte. The loop
+// remains available on browsers that do not implement Uint8Array.fromBase64.
+function decodeBase64(value) {
+  if(typeof Uint8Array.fromBase64==='function')return Uint8Array.fromBase64(value);
+  const binary=atob(value),bytes=new Uint8Array(binary.length);
+  for(let n=0;n<binary.length;n++)bytes[n]=binary.charCodeAt(n);
+  return bytes;
+}
+module.exports={decodeBase64};

package/compat/cache-handlers.cjs

@@ -139,10 +139,19 @@ async function customCachedValue(key, kind, producer, options) {
     const timestamp = Date.now();
     const record = { revision, timestamp, work: undefined, metadata: undefined };
     work = (async () => {
+      let lease,canStore=true;
+      try {
+      if(typeof handler.acquire==='function'){
+        try{
+          lease=await call(handler,'acquire',[key,{signal:context.signal}],context);
+          const shared=await call(handler,'get',[key,tags],context);
+          if(shared){const sharedInfo=metadata(shared);if(Date.now()-sharedInfo.timestamp<Math.min(sharedInfo.expire,sharedInfo.revalidate)*1000){record.metadata=sharedInfo;options.onReadMetadata?.(sharedInfo);return await read(shared,context);}void shared.value.cancel().catch(()=>{});}
+        }catch{context.signal?.throwIfAborted();canStore=false;}
+      }
       const result = await producer();
       const info = resolveMetadata();
       record.metadata = info;
-      if (result.byteLength <= MAX_BYTES && revision === (revisions.get(handler) || 0)) {
+      if (canStore && result.byteLength <= MAX_BYTES && revision === (revisions.get(handler) || 0)) {
         try {
           const changed = await expiration(handler, [...new Set([...tags, ...info.tags])], context);
           // Many backends record Date.now() millisecond timestamps. Treat the
@@ -150,12 +159,13 @@ async function customCachedValue(key, kind, producer, options) {
           // hide an invalidation which actually happened after the read started.
           if ((changed === Infinity || changed < Math.floor(timestamp)) && revision === (revisions.get(handler) || 0)) {
             const value = stream(result);
-            try { await call(handler, 'set', [key, Promise.resolve({ value, tags: info.tags, stale: info.stale, revalidate: info.revalidate, expire: info.expire, timestamp })], context); }
+            try { await call(handler, 'set', [key, Promise.resolve({ value, tags: info.tags, stale: info.stale, revalidate: info.revalidate, expire: info.expire, timestamp }),{lease,softTags:tags}], context); }
             catch { if (!value.locked) void value.cancel().catch(() => {}); }
           }
         } catch { context.signal?.throwIfAborted(); }
       }
       return result;
+      }finally{try{await lease?.release();}catch{/* A failed cache cleanup does not replay application work. */}}
     })();
     record.work = work;
     if (pendingCount < 64) {

package/compat/cache-wire.cjs

@@ -0,0 +1,28 @@
+'use strict';
+// Versioned private framing: bounded JSON metadata followed by uninterpreted bytes.
+const TYPE = 'application/vnd.prnext.cache-v2';
+const MAX_VALUE = 2 * 1024 * 1024;
+const MAX_META = 2 * 1024 * 1024;
+function encode(operation) {
+  const { value, ...metadata } = operation;
+  if (value !== undefined && !Buffer.isBuffer(value) && !(value instanceof Uint8Array)) throw new TypeError('Cache wire values must be bytes');
+  const bytes = value === undefined ? undefined : Buffer.isBuffer(value) ? value : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  if (bytes && (metadata.op !== 'commit' || bytes.length > MAX_VALUE)) throw new Error('Invalid cache wire value');
+  if (metadata.op === 'commit' && !bytes) throw new Error('Cache commit requires bytes');
+  const json = Buffer.from(JSON.stringify(metadata));
+  if (json.length > MAX_META) throw new Error('Cache wire metadata exceeds limit');
+  const prefix = Buffer.allocUnsafe(4); prefix.writeUInt32BE(json.length);
+  return bytes ? [prefix, json, bytes] : [prefix, json];
+}
+function decode(bytes) {
+  if (bytes.length < 4) throw new Error('Truncated cache wire frame');
+  const length = bytes.readUInt32BE(0);
+  if (length > MAX_META || length > bytes.length - 4) throw new Error('Invalid cache wire metadata length');
+  const value = JSON.parse(bytes.subarray(4, 4 + length).toString('utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid cache wire metadata');
+  const raw = bytes.subarray(4 + length);
+  if (raw.length > MAX_VALUE || (value.value !== true && raw.length) || (value.value !== undefined && value.value !== true)) throw new Error('Invalid cache wire payload');
+  if (value.value === true) value.value = raw;
+  return value;
+}
+module.exports = { TYPE, MAX_VALUE, MAX_META, encode, decode };

package/compat/cache.cjs

@@ -96,4 +96,5 @@ function unstable_noStore() {
 }
 function refresh() { cacheState(mutationContext('refresh', true)).refresh = true; }
 
-module.exports = { unstable_cache, revalidateTag, updateTag, revalidatePath, unstable_noStore, refresh, cacheTag, cacheLife };
+const { navigation, prefetch } = require('./navigation-stages.cjs');
+module.exports = { unstable_cache, revalidateTag, updateTag, revalidatePath, unstable_noStore, refresh, cacheTag, cacheLife, navigation, prefetch };

package/compat/cache.d.cts

@@ -34,3 +34,7 @@ export function updateTag(tag: string): void;
 export function revalidatePath(path: string, type?: 'page' | 'layout'): void;
 export function unstable_noStore(): void;
 export function refresh(): void;
+/** Defer runtime work until navigation, while allowing static prerenders. */
+export function navigation(): Promise<void>;
+/** Defer runtime work until a per-link prefetch or navigation. */
+export function prefetch(): Promise<void>;