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

package/cli.mjs

@@ -1,23 +1,24 @@
 #!/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 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 +29,17 @@ 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 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,6 +56,20 @@ 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, 2 invalid input or missing build.
 
 Server options: --port 3000 --hostname 127.0.0.1 --workers 1 --inspect
 Production profiles: --profile balanced|speed|memory|classic
@@ -78,6 +101,18 @@ 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 === '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 +185,41 @@ 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', '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'].includes(command) && args.some(arg => ['--help','-h'].includes(arg))) { console.log(help); 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 +263,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 +277,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,6 +291,17 @@ 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);
@@ -231,120 +313,22 @@ async function main() {
     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/index.d.ts

@@ -2,6 +2,8 @@
 import type { ComponentType } from 'react';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 export type { Metadata, Viewport, ResolvingMetadata, ResolvingViewport, MetadataRoute } from './metadata.cjs';
+export {route} from './typed-route.cjs';
+export type {Route, RoutePattern, RouteParameters} from './typed-route.cjs';
 
 export interface InstantSample {
   cookies?: Array<{name: string; value: string | null}>;
@@ -116,10 +118,12 @@ export interface NextConfig {
    * 0 disables the corresponding retirement; keepWarm retains one lane per used host.
    */
   workerRetirement?: { idleSeconds?: number; laneIdleSeconds?: number; keepWarm?: boolean };
-  /** Next dev page-retention hints; PRNext builds all routes without that eviction queue. */
+  /** Import selected Node routes on startup; top-level module code executes. RSS is a soft import budget. */
+  workerPreload?: false | { routes: string[]; maxRssMb?: number; timeoutMs?: number };
+  /** Bounded active development routes; default retains five requested routes. */
   onDemandEntries?: { maxInactiveAge?: number; pagesBufferLength?: number };
-  /** Disable the Next development indicator. Error overlays and Fast Refresh remain enabled. */
-  devIndicators?: false;
+  /** PRNext development menu; bottom-left by default. false hides it without disabling errors or Fast Refresh. */
+  devIndicators?: false | { position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' };
   i18n?: { locales: string[]; defaultLocale: string; localeDetection?: boolean; domains?: Array<{domain: string; defaultLocale: string; locales?: string[]; http?: boolean}> };
   webpack?: (config: import('webpack').Configuration, context: { buildId: string; dev: boolean; isServer: boolean; nextRuntime?: 'nodejs' | 'edge'; webpack: typeof import('webpack'); defaultLoaders: {babel: {loader: string}} }) => import('webpack').Configuration | Promise<import('webpack').Configuration>;
   turbopack?: { root?: string; rules?: Record<string, TurbopackRule | TurbopackRule[]>; resolveAlias?: Record<string, string | { browser: string }>; resolveExtensions?: string[] };
@@ -128,10 +132,12 @@ export interface NextConfig {
   reactStrictMode?: boolean;
   /** Enabled React Compiler transforms are not implemented. */
   reactCompiler?: false;
-  /** Typed route generation and validation are not implemented. */
-  typedRoutes?: false;
+  /** Generate route completions and validate Link/router destinations. */
+  typedRoutes?: boolean;
+  /** Native CSS for default styles; custom PostCSS pipelines remain authoritative. */
+  cssEngine?: 'auto'|'postcss'|'lightningcss';
   /** Production checks use the project's installed TypeScript without emitting files. */
-  typescript?: { ignoreBuildErrors?: boolean; tsconfigPath?: string };
+  typescript?: { ignoreBuildErrors?: boolean; tsconfigPath?: string; devChecks?: boolean };
   cacheComponents?: boolean;
   cacheLife?: Record<string, import('./cache.cjs').CacheLife>;
   transpilePackages?: string[];
@@ -191,9 +197,17 @@ export interface StaticBuildOptions {
   dev?: false;
 }
 export interface BuildResult { buildId: string; outputDirectory: string; }
+export interface ProductionBuilder {
+  build(options?: {envMode?: 'production' | 'test'}): Promise<BuildResult>;
+  stats(): {contexts: number; created: number; reused: number};
+  dispose(): Promise<void>;
+}
+export function createBuilder(projectRoot: string, options?: {envMode?: 'production' | 'test'}): Promise<ProductionBuilder>;
 export interface StaticBuildResult extends BuildResult { files: number; bytes: number; }
 export function build(projectRoot: string, options: StaticBuildOptions & { adapter: 'static' }): Promise<StaticBuildResult>;
-export function build(projectRoot: string, options?: { adapter?: 'react'; dev?: boolean; envMode?: 'production' | 'development' | 'test' }): Promise<BuildResult>;
+/** Detect a completed browser output or a PRNext React project; does not run another builder. */
+export function build(projectRoot: string, options: { adapter: 'auto'; dev?: false; spa?: boolean }): Promise<BuildResult | StaticBuildResult>;
+export function build(projectRoot: string, options?: { adapter?: 'react'; dev?: boolean; incremental?: boolean; envMode?: 'production' | 'development' | 'test' }): Promise<BuildResult>;
 export function buildStatic(projectRoot: string, options?: StaticBuildOptions): Promise<StaticBuildResult>;
 export function readBuildOutput(buildDirectory: string): Promise<BuildOutput>;
 export function validateBuildOutput(value: unknown): BuildOutput;

package/compat/link.d.cts

@@ -1,7 +1,8 @@
 import type { AnchorHTMLAttributes, ForwardRefExoticComponent, ReactNode, RefAttributes } from 'react';
 import type { UrlObject } from './router.cjs';
-export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
-  href: string | UrlObject;
+import type {Route,TypedUrlObject} from './typed-route.cjs';
+export interface LinkProps<T extends string=string> extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  href: Route<T> | TypedUrlObject;
   as?: string | UrlObject;
   replace?: boolean;
   scroll?: boolean;
@@ -13,5 +14,5 @@ export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>,
   children?: ReactNode;
   onNavigate?: (event: { preventDefault(): void }) => void;
 }
-declare const Link: ForwardRefExoticComponent<LinkProps & RefAttributes<HTMLAnchorElement>>;
+declare function Link<T extends string>(props:LinkProps<T> & RefAttributes<HTMLAnchorElement>): import('react').ReactElement|null;
 export default Link;

package/compat/navigation.d.cts

@@ -1,12 +1,13 @@
+import type {Route} from './typed-route.cjs';
 export interface NavigateOptions { scroll?: boolean }
 export interface PrefetchOptions { onInvalidate?: () => void }
 export interface AppRouterInstance {
-  push(href: string, options?: NavigateOptions): void;
-  replace(href: string, options?: NavigateOptions): void;
+  push<T extends string>(href: Route<T>, options?: NavigateOptions): void;
+  replace<T extends string>(href: Route<T>, options?: NavigateOptions): void;
   refresh(): void;
   back(): void;
   forward(): void;
-  prefetch(href: string, options?: PrefetchOptions): void;
+  prefetch<T extends string>(href: Route<T>, options?: PrefetchOptions): void;
 }
 export class ReadonlyURLSearchParams extends URLSearchParams {
   append(): never;

package/compat/router.d.cts

@@ -1,4 +1,5 @@
 import type { ComponentType, ReactNode, ReactElement } from 'react';
+import type {Route,TypedUrlObject} from './typed-route.cjs';
 export interface UrlObject {
   auth?: string | null;
   host?: string | null;
@@ -33,9 +34,9 @@ export interface PRNextRouter extends RouterSnapshot {
   isFallback: boolean;
   isPreview: boolean;
   basePath: string;
-  push(url: string | UrlObject, as?: string | UrlObject, options?: { scroll?: boolean; shallow?: boolean; locale?: string | false }): Promise<boolean>;
-  replace(url: string | UrlObject, as?: string | UrlObject, options?: { scroll?: boolean; shallow?: boolean; locale?: string | false }): Promise<boolean>;
-  prefetch(url: string | UrlObject, as?: string | UrlObject, options?: { priority?: boolean; locale?: string | false }): Promise<void>;
+  push<T extends string>(url: Route<T> | TypedUrlObject, as?: string | UrlObject, options?: { scroll?: boolean; shallow?: boolean; locale?: string | false }): Promise<boolean>;
+  replace<T extends string>(url: Route<T> | TypedUrlObject, as?: string | UrlObject, options?: { scroll?: boolean; shallow?: boolean; locale?: string | false }): Promise<boolean>;
+  prefetch<T extends string>(url: Route<T> | TypedUrlObject, as?: string | UrlObject, options?: { priority?: boolean; locale?: string | false }): Promise<void>;
   beforePopState(callback: (state: { url: string; as: string; options: { shallow?: boolean; scroll?: boolean } }) => boolean): void;
   events: RouterEvents;
   reload(): void;

package/compat/typed-route.d.cts

@@ -0,0 +1,17 @@
+import type {UrlObject} from './router.cjs';
+declare global { namespace PRNext { interface RouteMap {} interface RouteConfig {} } }
+type GeneratedRoutes = keyof PRNext.RouteMap extends never ? PRNext.RouteConfig extends {enabled:true} ? true : false : true;
+export type RoutePattern = GeneratedRoutes extends true ? Extract<keyof PRNext.RouteMap,string> : string;
+export type RouteParameters<P extends string> = P extends keyof PRNext.RouteMap ? PRNext.RouteMap[P] : Record<string,string|string[]|undefined>;
+type Suffix = '' | `?${string}` | `#${string}`;
+type External = `https://${string}` | `http://${string}` | `mailto:${string}` | `tel:${string}` | `#${string}` | `?${string}`;
+type Expand<P extends string> = P extends `${infer A}/[[...${string}]]` ? A | `${A}/${string}` : P extends `${infer A}[${string}]${infer B}` ? `${A}${string}${Expand<B>}` : P;
+type Strip<P extends string> = P extends `${infer A}#${string}` ? Strip<A> : P extends `${infer A}?${string}` ? A : P;
+type Segment<S extends string> = S extends ''|'.'|'..' ? false : S extends `${string}/${string}`|`${string}\\${string}` ? false : true;
+type Segments<S extends string> = S extends `${infer H}/${infer R}` ? Segment<H> extends true ? Segments<R> : false : Segment<S>;
+type Match<P extends string,S extends string> = P extends `${infer A}/[[...${string}]]` ? S extends A ? true : Match<`${A}/[...rest]`,S> : P extends `[...${string}]` ? Segments<S> : P extends `${infer H}/${infer R}` ? S extends `${infer V}/${infer T}` ? H extends `[${string}]` ? Segment<V> extends true ? Match<R,T> : false : H extends V ? Match<R,T> : false : false : P extends `[${string}]` ? Segment<S> : P extends S ? true : false;
+type Matching<S extends string,P extends string=RoutePattern> = P extends unknown ? Match<P,S> extends true ? true : never : never;
+type Suggestions = Expand<RoutePattern> extends infer P extends string ? `${P}${Suffix}` : never;
+export type Route<T extends string=string> = GeneratedRoutes extends false ? T : string extends T ? Suggestions|External : T extends External ? T : true extends Matching<Strip<T>> ? T : never;
+export type TypedUrlObject = GeneratedRoutes extends false ? UrlObject : {[P in RoutePattern]: Omit<UrlObject,'pathname'|'query'> & {pathname:P} & ({} extends RouteParameters<P> ? {query?:RouteParameters<P>&Record<string,unknown>} : {query:RouteParameters<P>&Record<string,unknown>})}[RoutePattern];
+export function route<P extends RoutePattern>(pattern:P,...args:{} extends RouteParameters<P> ? [params?:RouteParameters<P>] : [params:RouteParameters<P>]): Route;

package/docs/ai/compatibility.md

@@ -0,0 +1,106 @@
+# Compatibility and migration
+
+[AI documentation index](../../AI.md)
+
+## Treat compatibility as a checked contract
+
+PRNext adapts many public Next.js conventions; it is not a drop-in implementation
+of every Next.js version. Package installation, a recognized import or a green
+source audit does not prove an application works. The installed package's
+metadata, declarations, diagnostics and executable behavior are the authority
+for this release. Do not use an old repository checklist to override them.
+
+Common supported areas include App/Pages routing, React Server Components,
+Server Actions, request APIs, navigation, route metadata, supported cache APIs,
+CSS Modules and the project's PostCSS pipeline. Scope varies by runtime and
+option. Advanced parallel/intercepting routing, custom webpack/loaders, package
+transpilation, image/font tooling and caching deserve targeted build and browser
+tests. Support for one configuration shape does not imply support for all
+upstream plugin behavior.
+
+Configuration uses one `next.config.*` or `prnext.config.*` file and rejects
+unknown keys rather than ignoring them. `reactCompiler: false` is accepted;
+enabling React Compiler is explicitly unsupported. `typedRoutes: true` is
+implemented through PRNext's generated route registry. Do not copy a full
+Next.js configuration template into a new application.
+
+Only explicit private Next.js import adapters are supported. Do not add arbitrary
+`next/dist/...` imports or install another Next runtime to satisfy one: isolate
+or replace the incompatible dependency, retain the original framework where
+needed, and describe the limitation honestly.
+
+## Migrate conservatively
+
+Use the project's existing package manager. For npm, install the intended
+published PRNext release and its matching React peers, then inspect the dry run:
+
+```sh
+npm i --save-exact @thomas.f/prnext react@19.3.1 react-dom@19.3.1 react-server-dom-webpack@19.3.1
+npx --no-install prnext migrate --dry-run
+npx --no-install prnext migrate --check --json
+```
+
+Review scripts, manager/workspace detection, configuration and reported source
+conflicts. When the plan is correct:
+
+```sh
+npx --no-install prnext migrate
+npx --no-install prnext check --json
+npx --no-install prnext typecheck
+npx --no-install prnext build
+```
+
+Migration changes selected scripts/dependencies, backs up package files and
+existing lockfiles, and keeps Next.js and application source. Public `next/*`
+imports can remain. Do not remove Next, replace all imports or recreate the
+application without a separate need.
+
+Installation honors npm, pnpm and Yarn Classic/Berry and the owning workspace
+root. Conflicting managers, unsafe filesystem entries and unlisted workspaces
+can block automatic install. `migrate --no-install` prepares the manifest for
+manual manager execution. Custom shell scripts may require a manual edit.
+An installation failure attempts safe manifest/lockfile restoration; it cannot
+roll back every dependency directory or manager cache. Never solve peer conflicts
+by silently adding `--force` or `--legacy-peer-deps`.
+
+`migrate --check` audits without applying a migration. Configuration evaluation
+can run project code, and installed custom loaders still require a real build.
+The audit is not a sandbox for untrusted projects.
+
+## Compare running applications
+
+Start the original application and the candidate on separate available ports.
+Create `paths.json` with representative concrete URLs:
+
+```json
+["/", "/products/demo", "/api/health"]
+```
+
+Then compare public GET responses:
+
+```sh
+prnext migrate --check --against http://localhost:3000 --candidate http://localhost:3001 --routes paths.json
+```
+
+The comparison does not authenticate or follow redirects. It compares response
+samples, including status, content type and selected body semantics; it does not
+prove hydration, styling, actions or all dynamic routes. Visit important routes
+in a real browser, test authorized and unauthorized states, and run the existing
+application tests. Keep the original setup available until the candidate is
+actually verified. Timings from this comparison are not controlled benchmarks.
+
+## Boundaries that often matter
+
+React server/client directives in `.mts`/`.cts` are rejected; use `.ts`/`.tsx`.
+App Route Handlers use Web Request/Response, while Pages APIs retain their own
+request/response contract. App and Pages router hooks are not interchangeable.
+Edge code cannot assume Node APIs or Node-only package behavior.
+
+HTTP/1 WebSockets can tunnel through supported external HTTP(S) rewrites and
+hosting gateways; App/Pages handlers do not gain a WebSocket server API. Static
+imports accept completed public browser output, not another framework's SSR
+server. See [Deployment](deployment.md) before choosing an adapter.
+
+When a feature is missing, give its exact failing API/option and a supported
+alternative. Do not claim full compatibility, invent a replacement method or
+mask the error with an empty shim.