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

package/native/diagnostics.mjs

@@ -0,0 +1,34 @@
+import { packageManifest, nativePlatform, resolveNativeBinary } from './resolve.mjs';
+
+// The package's Node engines use explicit minimum versions and major ranges.
+// Keep this check local: a diagnostic must never fetch package metadata.
+export function supportedNode(version, range = packageManifest.engines.node) {
+  const parsed = /^(?:v)?(\d+)\.(\d+)\.(\d+)(?:\+[^\s]+)?$/.exec(version);
+  if (!parsed) return false;
+  const actual = parsed.slice(1).map(Number);
+  return range.split('||').some(part => {
+    const match = /^\s*(\^|>=)(\d+)\.(\d+)\.(\d+)\s*$/.exec(part);
+    if (!match) return false;
+    const minimum = match.slice(2).map(Number);
+    const compared = actual[0] - minimum[0] || actual[1] - minimum[1] || actual[2] - minimum[2];
+    return compared >= 0 && (match[1] !== '^' || actual[0] === minimum[0]);
+  });
+}
+
+/** Inspect installation metadata and executable access; never execute or build it. */
+export async function environmentDiagnostics({ version = process.version, platform = process.platform, arch = process.arch,
+  libc, env = process.env, resolve = resolveNativeBinary } = {}) {
+  const diagnostics = [];
+  diagnostics.push(supportedNode(version)
+    ? { id: 'node', severity: 'info', message: `Node ${version} satisfies ${packageManifest.engines.node}.` }
+    : { id: 'node', severity: 'error', message: `Node ${version} is unsupported.`, action: `Use Node ${packageManifest.engines.node}.` });
+  try {
+    const target = env.PRNEXT_BINARY ? null : nativePlatform({ platform, arch, libc });
+    await resolve({ env, allowBuild: false, platform: { platform, arch, libc } });
+    diagnostics.push({ id: 'native', severity: 'info', message: `Native executable is accessible for ${platform}/${arch}${target?.libc ? `/${target.libc}` : ''}; metadata/access checked without running it.`, ...(target ? { package: target.package } : { override: true }) });
+  } catch (error) {
+    diagnostics.push({ id: 'native', severity: 'error', message: error.message,
+      action: 'Install matching PRNext optional dependencies on this machine. For a source checkout, build the native server explicitly; check never builds it.' });
+  }
+  return diagnostics;
+}

package/native/resolve.mjs

@@ -14,10 +14,15 @@ export const nativeBinaryName = (platform = process.platform) => platform === 'w
 // the framework checkout, even if that consumer also has a Cargo workspace.
 export function sourceCheckout(root = packageRoot) {
   try {
-    const repository = path.resolve(root, '../..');
+    // Package-manager portals and linked checkouts may expose a virtual path.
+    // Establish the physical package root before looking for its repository.
+    // The native resolver also expands Windows DOS aliases and canonicalizes
+    // junction target casing; the JS resolver preserves their stored spelling.
+    const canonicalRoot = realpathSync.native(root);
+    const repository = path.resolve(canonicalRoot, '../..');
     const manifest = JSON.parse(readFileSync(path.join(repository, 'package.json'), 'utf8'));
     if (manifest.name !== 'prnext-monorepo' || manifest.private !== true) return null;
-    if (realpathSync(root) !== realpathSync(path.join(repository, 'packages/prnext'))) return null;
+    if (canonicalRoot !== realpathSync.native(path.join(repository, 'packages/prnext'))) return null;
     readFileSync(path.join(repository, 'crates/prnext/Cargo.toml'));
     return repository;
   } catch { return null; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thomas.f/prnext",
-  "version": "0.1.16-alpha",
+  "version": "0.1.17-alpha",
   "license": "MIT",
   "description": "Experimental Rust-powered runtime for Next.js apps, React and npm",
   "homepage": "https://prnext.dev",
@@ -33,6 +33,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
+    "AI.md",
+    "docs/ai/",
     "cli.mjs",
     "index.mjs",
     "build/",
@@ -49,6 +51,14 @@
     "prn": "./cli.mjs"
   },
   "exports": {
+    "./AI.md": "./AI.md",
+    "./docs/ai/manifest.json": "./docs/ai/manifest.json",
+    "./docs/ai/quickstart.md": "./docs/ai/quickstart.md",
+    "./docs/ai/routing.md": "./docs/ai/routing.md",
+    "./docs/ai/data.md": "./docs/ai/data.md",
+    "./docs/ai/compatibility.md": "./docs/ai/compatibility.md",
+    "./docs/ai/deployment.md": "./docs/ai/deployment.md",
+    "./docs/ai/troubleshooting.md": "./docs/ai/troubleshooting.md",
     "./package.json": "./package.json",
     "./og": {
       "types": "./compat/og.d.cts",
@@ -66,6 +76,10 @@
       "types": "./compat/index.d.ts",
       "default": "./index.mjs"
     },
+    "./route": {
+      "types": "./compat/typed-route.d.cts",
+      "default": "./runtime/typed-route.mjs"
+    },
     "./link": "./compat/link.cjs",
     "./head": "./compat/head.cjs",
     "./script": {
@@ -111,11 +125,15 @@
     "@babel/types": "^7.29.0",
     "@edge-runtime/vm": "5.0.0",
     "@vercel/nft": "1.11.0",
+    "browserslist": "4.29.0",
     "dotenv": "16.6.1",
     "dotenv-expand": "11.0.7",
     "esbuild": "^0.28.2",
     "fontkit": "2.0.4",
+    "html-to-image": "1.11.13",
+    "lightningcss": "1.31.0",
     "loader-runner": "4.3.2",
+    "oxc-parser": "0.155.0",
     "path-to-regexp": "6.3.0",
     "picomatch": "4.0.7",
     "postcss": "8.5.28",
@@ -132,12 +150,12 @@
     "react-server-dom-webpack": "19.3.1"
   },
   "optionalDependencies": {
-    "prnext-darwin-arm64": "0.1.16-alpha",
-    "prnext-darwin-x64": "0.1.16-alpha",
-    "prnext-linux-arm64-gnu": "0.1.16-alpha",
-    "prnext-linux-x64-gnu": "0.1.16-alpha",
-    "@thomas.f/prnext-win32-x64-msvc": "0.1.16-alpha",
-    "@thomas.f/prnext-win32-arm64-msvc": "0.1.16-alpha"
+    "@thomas.f/prnext-win32-arm64-msvc": "0.1.17-alpha",
+    "@thomas.f/prnext-win32-x64-msvc": "0.1.17-alpha",
+    "prnext-darwin-arm64": "0.1.17-alpha",
+    "prnext-darwin-x64": "0.1.17-alpha",
+    "prnext-linux-arm64-gnu": "0.1.17-alpha",
+    "prnext-linux-x64-gnu": "0.1.17-alpha"
   },
   "engines": {
     "node": "^22.23.4 || ^24.22.1 || >=26.12.1"

package/release/ai-docs.mjs

@@ -0,0 +1,48 @@
+import { readFile, access } from 'node:fs/promises';
+import path from 'node:path';
+
+const expectedTopics = ['quickstart', 'routing', 'data', 'compatibility', 'deployment', 'troubleshooting'];
+
+// These guides ship as package API. Validate their distribution and local links
+// on every release, independently of a website or a native server installation.
+export async function verifyAiDocumentation(root, pkg) {
+  if (!pkg.files?.includes('AI.md') || !pkg.files?.includes('docs/ai/')) {
+    throw new Error('The npm files list must include AI.md and docs/ai/.');
+  }
+  const manifest = JSON.parse(await readFile(path.join(root, 'docs/ai/manifest.json'), 'utf8'));
+  if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.topics) ||
+      JSON.stringify(manifest.topics.map(topic => topic.id)) !== JSON.stringify(expectedTopics)) {
+    throw new Error('AI documentation manifest has missing, duplicate or unexpected topics.');
+  }
+  const files = ['AI.md'];
+  for (const topic of manifest.topics) {
+    if (topic.file !== `docs/ai/${topic.id}.md` || typeof topic.title !== 'string' || !topic.title.trim() || /[\r\n\x00-\x1f]/.test(topic.title)) {
+      throw new Error(`Invalid AI documentation topic: ${topic.id}`);
+    }
+    files.push(topic.file);
+  }
+  for (const file of [...files, 'docs/ai/manifest.json']) {
+    if (pkg.exports?.[`./${file}`] !== `./${file}`) throw new Error(`Missing npm documentation export: ${file}`);
+  }
+  let totalBytes = 0;
+  for (const file of files) {
+    const content = await readFile(path.join(root, file), 'utf8');
+    const bytes = Buffer.byteLength(content);
+    totalBytes += bytes;
+    if (!/^# .+/m.test(content) || bytes > (file === 'AI.md' ? 6_000 : 32_000)) {
+      throw new Error(`AI guide is missing its heading or exceeds its focused reading budget: ${file}`);
+    }
+    for (const match of content.matchAll(/\[[^\]\n]+\]\(([^)\s]+)\)/g)) {
+      const link = match[1];
+      if (link.startsWith('#') || /^https?:\/\//.test(link)) continue;
+      const target = path.resolve(root, path.dirname(file), decodeURIComponent(link.split('#')[0]));
+      const relative = path.relative(root, target);
+      if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`AI guide link leaves the package: ${file}: ${link}`);
+      try { await access(target); }
+      catch { throw new Error(`Broken AI guide link: ${file}: ${link}`); }
+    }
+  }
+  if (totalBytes > 100_000) throw new Error('AI documentation exceeds the total focused reading budget.');
+  await access(path.join(root, 'runtime/ai-docs.mjs'));
+  return { topics: manifest.topics.length, files: files.length, bytes: totalBytes };
+}

package/release/verify.mjs

@@ -2,6 +2,7 @@ import { readFile, access } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { packageRoot, packageManifest, platforms, sourceCheckout } from '../native/resolve.mjs';
+import { verifyAiDocumentation } from './ai-docs.mjs';
 
 export async function verifyPackage() {
   const pkg = packageManifest;
@@ -25,6 +26,7 @@ export async function verifyPackage() {
     for (const target of Object.values(value)) await exported(target);
   }
   await exported(pkg.exports);
+  await verifyAiDocumentation(packageRoot, pkg);
   await access(path.join(packageRoot, 'runtime/profiles.json'));
   for (const name of ['index.node.mjs', 'resvg.wasm', 'hb.wasm', 'Geist-Regular.ttf', 'LICENSE', 'LICENSE.fflate', 'LICENSE.Geist', 'LICENSE.harfbuzzjs', 'LICENSE.satori', 'NOTICE.txt']) await access(path.join(packageRoot, 'runtime/og', name));
   if (pkg.dependencies['@vercel/og'] || (await readFile(path.join(packageRoot, 'runtime/og/index.node.mjs'), 'utf8')).includes('fflate@0.7.3')) throw new Error('OG renderer still depends on vulnerable upstream fflate. Run scripts/prepare-og.mjs.');

package/runtime/ai-docs.mjs

@@ -0,0 +1,202 @@
+import fs, {constants} from 'node:fs';
+import {lstat, open, realpath, unlink} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const defaultPackageRoot = fileURLToPath(new URL('../', import.meta.url));
+const maxDocumentBytes = 256 * 1024;
+const maxInstructionsBytes = 1024 * 1024;
+const startMarker = '<!-- prnext-ai-docs:start -->';
+const endMarker = '<!-- prnext-ai-docs:end -->';
+const noFollow = constants.O_NOFOLLOW || 0;
+
+const help = `Usage: prnext docs --ai [topic] [--json]
+       prnext docs --ai --list [--json]
+       prnext docs --ai --init [directory] [--json]
+
+Read the AI documentation shipped with the installed PRNext package.
+With no topic, print the short documentation index. --list shows available topics.
+--init explicitly appends a short documentation pointer to a project's AGENTS.md.
+Existing instructions are preserved; no files are changed by documentation reads.
+For initialization, use a physical directory path without symbolic links or junctions.
+No native binary, project configuration, network access, or installation is needed.
+`;
+
+function parseArguments(args) {
+  if (!Array.isArray(args) || args.some(arg => typeof arg !== 'string')) throw new Error('Documentation arguments must be strings.');
+  if (args.includes('--help') || args.includes('-h')) {
+    if (args.every(arg => ['--ai', '--help', '-h'].includes(arg))) return {help: true};
+    throw new Error('Use prnext docs --help without other documentation options.');
+  }
+  const flags = new Set(), positional = [];
+  for (const arg of args) {
+    if (['--ai', '--list', '--json', '--init'].includes(arg)) {
+      if (flags.has(arg)) throw new Error(`Duplicate documentation option: ${arg}`);
+      flags.add(arg);
+    } else if (arg.startsWith('-')) throw new Error(`Unknown documentation option: ${arg}`);
+    else positional.push(arg);
+  }
+  if (!flags.has('--ai')) throw new Error('Use prnext docs --ai to read the installed AI documentation.');
+  if (positional.length > 1) throw new Error('Provide only one documentation topic or initialization directory.');
+  if (flags.has('--list') && (flags.has('--init') || positional.length)) throw new Error('--list cannot be combined with a topic or --init.');
+  return {list: flags.has('--list'), json: flags.has('--json'), init: flags.has('--init'), value: positional[0]};
+}
+
+async function readBounded(handle, limit, label) {
+  const info = await handle.stat();
+  if (!info.isFile()) throw new Error(`${label} must be a regular file.`);
+  if (info.size > limit) throw new Error(`${label} exceeds the ${limit}-byte limit.`);
+  const buffer = Buffer.alloc(limit + 1);
+  let size = 0;
+  while (size < buffer.length) {
+    const {bytesRead} = await handle.read(buffer, size, buffer.length - size, size);
+    if (!bytesRead) break;
+    size += bytesRead;
+  }
+  if (size > limit) throw new Error(`${label} exceeds the ${limit}-byte limit.`);
+  return buffer.subarray(0, size);
+}
+
+function decodeUtf8(buffer, label) {
+  try { return new TextDecoder('utf-8', {fatal: true, ignoreBOM: true}).decode(buffer); }
+  catch { throw new Error(`${label} must contain UTF-8 text.`); }
+}
+
+async function readPackageFile(root, relative, limit = maxDocumentBytes) {
+  const file = path.resolve(root, relative);
+  const canonicalRoot = await realpath(root), canonicalFile = await realpath(file);
+  const inside = path.relative(canonicalRoot, canonicalFile);
+  if (inside.startsWith(`..${path.sep}`) || inside === '..' || path.isAbsolute(inside)) throw new Error(`Documentation file escapes the installed package: ${relative}`);
+  const handle = await open(file, constants.O_RDONLY);
+  try { return decodeUtf8(await readBounded(handle, limit, relative), relative); }
+  finally { await handle.close(); }
+}
+
+async function readCatalog(root) {
+  const metadata = JSON.parse(await readPackageFile(root, 'package.json', 64 * 1024));
+  if (typeof metadata.name !== 'string' || typeof metadata.version !== 'string') throw new Error('The installed package metadata has no name or version.');
+  const manifest = JSON.parse(await readPackageFile(root, 'docs/ai/manifest.json', 64 * 1024));
+  if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.topics) || manifest.topics.length > 64) throw new Error('The AI documentation manifest must use schemaVersion 1 and contain a bounded topics array.');
+  const topics = [{id: 'index', title: 'AI documentation index', file: 'AI.md'}], ids = new Set(['index']);
+  for (const topic of manifest.topics) {
+    if (!topic || !/^[a-z][a-z0-9-]*$/.test(topic.id) || ids.has(topic.id)
+      || typeof topic.title !== 'string' || !topic.title.trim() || /[\r\n\x00-\x1f]/.test(topic.title)
+      || topic.file !== `docs/ai/${topic.id}.md`) throw new Error('The AI documentation manifest contains an invalid or duplicate topic.');
+    ids.add(topic.id);
+    topics.push({id: topic.id, title: topic.title, file: topic.file});
+  }
+  return {name: metadata.name, version: metadata.version, topics};
+}
+
+function instructionBlock(newline) {
+  return [startMarker, '## PRNext documentation', '',
+    'Before changing PRNext configuration, routes, data fetching, or deployment, read the documentation shipped with the installed package:', '',
+    '`npx --no-install prnext docs --ai`', '',
+    'Use `npx --no-install prnext docs --ai --list` to find topics, then read only the relevant topic with `npx --no-install prnext docs --ai <topic>`.',
+    'With pnpm or Yarn, use `pnpm exec prnext docs --ai` or `yarn prnext docs --ai` instead. The installed package documentation is the version-specific reference; do not assume full Next.js compatibility.',
+    endMarker, ''].join(newline);
+}
+
+function samePath(left, right) {
+  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+async function checkDirectory(directory) {
+  const parts = path.relative(path.parse(directory).root, directory).split(path.sep).filter(Boolean);
+  let current = path.parse(directory).root;
+  for (const part of parts) {
+    current = path.join(current, part);
+    const info = await lstat(current);
+    if (info.isSymbolicLink()) throw new Error(`Refusing to initialize through a symbolic link or junction: ${current}`);
+    if (!info.isDirectory()) throw new Error(`Initialization directory is not a directory: ${current}`);
+  }
+  if (!samePath(await realpath(directory), directory)) throw new Error('Initialization directory resolves outside its requested path.');
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function verifyTarget(directory, file, handle) {
+  await checkDirectory(directory);
+  const actual = await lstat(file), opened = await handle.stat();
+  if (actual.isSymbolicLink() || !actual.isFile() || !sameFile(actual, opened) || opened.nlink !== 1) {
+    throw new Error('AGENTS.md changed identity or is linked; no instructions were appended.');
+  }
+}
+
+function hasPointer(content) {
+  const starts = content.split(startMarker).length - 1, ends = content.split(endMarker).length - 1;
+  if (!starts && !ends) return false;
+  if (starts !== 1 || ends !== 1 || content.indexOf(startMarker) > content.indexOf(endMarker)) {
+    throw new Error('AGENTS.md contains incomplete or duplicate PRNext documentation markers; preserve and fix those markers before initializing again.');
+  }
+  return true;
+}
+
+async function initializeInstructions(directory) {
+  await checkDirectory(directory);
+  const file = path.join(directory, 'AGENTS.md'), lockFile = path.join(directory, '.prnext-ai-docs.lock');
+  let lock;
+  try { lock = await open(lockFile, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow, 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`Another initialization or an existing lock prevents changes: ${lockFile}`);
+    throw error;
+  }
+  let handle;
+  try {
+    await checkDirectory(directory);
+    let existing;
+    try { existing = await lstat(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (existing && (existing.isSymbolicLink() || !existing.isFile() || existing.nlink !== 1)) throw new Error('AGENTS.md must be a regular file with no symbolic or hard links.');
+    handle = await open(file, existing
+      ? constants.O_RDWR | constants.O_APPEND | noFollow
+      : constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_EXCL | noFollow, 0o644);
+    await verifyTarget(directory, file, handle);
+    const before = await readBounded(handle, maxInstructionsBytes, 'AGENTS.md');
+    const content = decodeUtf8(before, 'AGENTS.md');
+    if (hasPointer(content)) return {path: file, changed: false};
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const separator = !content ? '' : content.endsWith(newline + newline) ? '' : content.endsWith(newline) ? newline : newline + newline;
+    const addition = Buffer.from(separator + instructionBlock(newline));
+    if (before.length + addition.length > maxInstructionsBytes) throw new Error('Appending the PRNext pointer would exceed the AGENTS.md size limit.');
+    // Append through the verified handle: concurrent appends never get replaced by
+    // a stale full-file write. Refuse observed edits or target replacement.
+    if (!before.equals(await readBounded(handle, maxInstructionsBytes, 'AGENTS.md'))) throw new Error('AGENTS.md changed during initialization; retry without overwriting those edits.');
+    await verifyTarget(directory, file, handle);
+    await handle.writeFile(addition);
+    // Yarn PnP wraps FileHandle.sync() with an unimplemented method, even for
+    // physical project files. Its descriptor still supports callback fsync.
+    await new Promise((resolve, reject) => fs.fsync(handle.fd, error => error ? reject(error) : resolve()));
+    return {path: file, changed: true};
+  } finally {
+    await handle?.close();
+    // Only remove the lock we created, never a replacement supplied by another process.
+    try {
+      const opened = await lock.stat(), actual = await lstat(lockFile);
+      if (sameFile(opened, actual) && !actual.isSymbolicLink()) await unlink(lockFile);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    finally { await lock.close(); }
+  }
+}
+
+/** Read bundled docs or explicitly append a project pointer. Never launches native code. */
+export async function executeAiDocs(args, {cwd = process.cwd(), packageRoot = defaultPackageRoot} = {}) {
+  const options = parseArguments(args);
+  if (options.help) return {output: help};
+  const catalog = await readCatalog(packageRoot);
+  if (options.init) {
+    const initialized = await initializeInstructions(path.resolve(cwd, options.value || '.'));
+    const result = {name: catalog.name, version: catalog.version, initialized};
+    return {initialized, output: options.json ? JSON.stringify(result, null, 2) + '\n'
+      : `${initialized.changed ? 'Added the PRNext documentation pointer to' : 'Kept the existing PRNext documentation pointer in'} ${initialized.path}\n`};
+  }
+  if (options.list) return {output: options.json ? JSON.stringify(catalog, null, 2) + '\n'
+    : `${catalog.name} ${catalog.version}\n\n${catalog.topics.map(topic => `${topic.id.padEnd(18)} ${topic.title}`).join('\n')}\n`};
+  const id = options.value || 'index';
+  const topic = catalog.topics.find(item => item.id === id);
+  if (!topic) throw new Error(`Unknown AI documentation topic: ${id}. Use prnext docs --ai --list.`);
+  const content = await readPackageFile(packageRoot, topic.file);
+  return {output: options.json ? JSON.stringify({...catalog, topic: topic.id, content}, null, 2) + '\n'
+    : `${catalog.name} ${catalog.version} — ${topic.title}\n\n${content}${content.endsWith('\n') ? '' : '\n'}`};
+}

package/runtime/app-client.mjs

@@ -242,7 +242,8 @@ async function startApp({ clientModules = {}, basePath = '', trailingSlash = fal
     }
   }
 
-  async function requestFlight(url, signal, routing = currentRouting, onPartial) {
+  async function requestFlight(url, signal, routing = currentRouting, onPartial, {skipEnsure=false}={}) {
+    if(process.env.NODE_ENV==='development'&&!routing?.refresh&&!skipEnsure)await globalThis.__PRNEXT_DEV__?.ensureRoute?.(url.href);
     const exported = window.__PRNEXT_STATIC_EXPORT__ === true;
     const target = exported ? new URL(basePath + '/_prnext/flight' + (url.pathname.slice(basePath.length).replace(/\/$/, '') || '') + '/index.txt', url) : url;
     const response = await fetch(target.href, {
@@ -444,7 +445,10 @@ async function startApp({ clientModules = {}, basePath = '', trailingSlash = fal
       } else {
         const abort = new AbortController();
         activeRequest = abort;
-        result = await requestFlight(target, abort.signal, pop && savedRouting ? { ...savedRouting, restore: true } : refresh && currentRouting ? { ...currentRouting, refresh: true } : currentRouting);
+        // A refresh is already inside the compiler's apply transaction. Calling
+        // ensureRoute from here can wait for that same transaction forever when
+        // this tree has no routing state (the ordinary single-route case).
+        result = await requestFlight(target, abort.signal, pop && savedRouting ? { ...savedRouting, restore: true } : refresh && currentRouting ? { ...currentRouting, refresh: true } : currentRouting, undefined, {skipEnsure:refresh});
       }
       if (token !== navigation) return;
       if (!isApplicationURL(result.url, window.location.origin, basePath)) throw new Error('The navigation destination requires a document request');
@@ -459,7 +463,8 @@ async function startApp({ clientModules = {}, basePath = '', trailingSlash = fal
       const committed = () => {
         if (token === navigation && scroll && !refresh) scrollToTarget(result.url, savedScroll);
       };
-      startTransition(() => root.render(appView({ model: result.model, controller, committed, url: result.url.href, globalErrorComponent, globalErrorCss })));
+      if(process.env.NODE_ENV==='development'&&refresh)await new Promise(resolve=>startTransition(()=>root.render(appView({model:result.model,controller,committed:()=>{committed();resolve();},url:result.url.href,globalErrorComponent,globalErrorCss}))));
+      else startTransition(() => root.render(appView({ model: result.model, controller, committed, url: result.url.href, globalErrorComponent, globalErrorCss })));
     } catch (error) {
       if (token !== navigation || error?.name === 'AbortError') return;
       // Pages Router routes, public files, and unavailable Flight endpoints use
@@ -496,7 +501,9 @@ async function startApp({ clientModules = {}, basePath = '', trailingSlash = fal
     },
   };
 
-  const initialView = appView({ model: initialModel, controller, globalErrorComponent, globalErrorCss });
+  let resolveDevReady;
+  const devReady=process.env.NODE_ENV==='development'?new Promise(resolve=>{resolveDevReady=resolve;}):undefined;
+  const initialView = appView({ model: initialModel, controller, globalErrorComponent, globalErrorCss, ...(devReady?{committed:resolveDevReady}:{}) });
   const rootOptions = {
     formState: initialModel.formState ?? null,
     onCaughtError(error) {
@@ -506,7 +513,10 @@ async function startApp({ clientModules = {}, basePath = '', trailingSlash = fal
       }
     },
     onRecoverableError(error) {
-      if (!getNavigationControl(error) && !isDynamicBailout(error) && !isDynamicBailout(error?.cause)) console.error(error);
+      if (!getNavigationControl(error) && !isDynamicBailout(error) && !isDynamicBailout(error?.cause)) {
+        console.error(error);
+        if (process.env.NODE_ENV === 'development') globalThis.__PRNEXT_DEV__?.reportRecoverableError(error);
+      }
     },
   };
   if (document.documentElement.id === '__prnext_error__') {
@@ -525,8 +535,9 @@ async function startApp({ clientModules = {}, basePath = '', trailingSlash = fal
     scrollFrame = requestAnimationFrame(() => { scrollFrame = undefined; saveScroll(); });
   }, { passive: true });
   return { root, router: controller, ...(process.env.NODE_ENV === 'development' ? {
+    devReady,
     devPrepare: options => moduleLoader.updateModules(options.clientModules),
-    devCommit: () => controller.refresh(),
+    devCommit: () => {invalidatePrefetches();return navigate(new URL(window.location.href),{refresh:true});},
   } : {}) };
 }
 

package/runtime/app-render.mjs

@@ -233,6 +233,18 @@ function getWorker(production) {
   current.unref();
   return current;
 }
+export async function preloadAppRoutes(files,options){
+  const worker=getWorker(true),id=`preload-${++nextId}`;
+  worker.ref();
+  try{await new Promise((resolve,reject)=>{
+    const clean=()=>{clearTimeout(timer);worker.off('message',message);worker.off('error',error);worker.off('exit',exit);};
+    const message=value=>{if(value.type==='preloaded'&&value.id===id){clean();value.error?reject(new Error(value.error)):resolve();}};
+    const error=value=>{clean();reject(value);};const exit=()=>error(new Error('RSC worker exited while preloading'));
+    const timer=setTimeout(()=>{clean();void lifecycles.get(worker)?.terminate(new Error('RSC preload timed out'));reject(new Error('RSC preload timed out'));},options.timeoutMs);
+    worker.on('message',message);worker.once('error',error);worker.once('exit',exit);
+    worker.postMessage({type:'preload',id,value:{files,options}});
+  });}finally{if(!hasPending(worker)&&!lifecycles.get(worker)?.retiring)worker.unref();}
+}
 
 // Stdio workers can retain referenced MessagePorts after rendering (including
 // diagnostics piped from the RSC isolate). EOF must drain real cache/after()

package/runtime/cloud/archive.mjs

@@ -237,12 +237,10 @@ export async function archiveProject(
           throw new Error('package.json is not valid JSON.');
         }
         if (
-          !packageJson ||
-          typeof packageJson.scripts?.build !== 'string' ||
-          !packageJson.scripts.build.trim()
+          !packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)
         )
           throw new Error(
-            'Add a production build script to package.json before deploying.'
+            'package.json must contain an object.'
           );
       }
       let compressed = deflateRawSync(contents, { level: 6 });
@@ -291,10 +289,11 @@ export async function archiveProject(
     }
   }
   await walk();
-  if (!packageJson)
+  if (!files.includes('index.html') && (typeof packageJson?.scripts?.build !== 'string' || !packageJson.scripts.build.trim()))
     throw new Error(
-      'The selected directory needs a package.json with a build script; do not exclude it.'
+      'Include index.html for a plain site, or package.json with a production build script; do not exclude it.'
     );
+  packageJson ||= {};
   const end = Buffer.alloc(22);
   end.writeUInt32LE(0x06054b50);
   end.writeUInt16LE(files.length, 8);

package/runtime/compile-cache.mjs

@@ -0,0 +1,8 @@
+import {flushCompileCache} from 'node:module';
+let pending;
+// Flush after imports settle so later workers can reuse compiled code even
+// while this worker stays warm. Disk failure is an optimization miss only.
+export function scheduleCompileCacheFlush(){
+  if(pending||!process.env.NODE_COMPILE_CACHE||process.env.NODE_DISABLE_COMPILE_CACHE==='1')return;
+  pending=setTimeout(()=>{pending=undefined;try{flushCompileCache();}catch{}},1000);pending.unref();
+}

package/runtime/dev-ai-brands.mjs

@@ -0,0 +1,26 @@
+// Offline identification marks copied from PRNext Host's local assets:
+// hosting/public/assets/ai-icons/{codex,cursor,claude,other}.svg (vendored 2026-10-20).
+// Provenance retained from that directory's README:
+// - Codex/OpenAI: official Codex VS Code extension 26.1007.21434,
+//   resources/blossom-white.svg (OpenAI blossom mark).
+// - Cursor: official https://cursor.com/marketing-static/favicon.svg;
+//   brand guidance https://cursor.com/brand.
+// - Claude: official https://claude.com/favicon.svg (also claude.ai/favicon.svg).
+// Brand marks remain their owners' trademarks; no trademark-license or
+// endorsement claim is made. Geometry/colors are preserved. Only decorative
+// accessibility attributes, display size and Cursor's local clip ID are changed.
+// The generic MCP symbol is local, unbranded and inherits the text color.
+// These strings are trusted constants only; never interpolate remote markup.
+
+const codexIcon="<svg width=\"20\" height=\"20\" aria-hidden=\"true\" focusable=\"false\"\n  xmlns=\"http://www.w3.org/2000/svg\"\n \n \n  fill=\"none\"\n  viewBox=\"0 0 24 24\"\n>\n  <path\n    d=\"M13.798 23.976a5.7 5.7 0 0 1-2.26-.456 6.1 6.1 0 0 1-1.903-1.27 5.7 5.7 0 0 1-1.88.311 5.75 5.75 0 0 1-2.95-.79 6.2 6.2 0 0 1-2.188-2.159q-.81-1.366-.809-3.045 0-.695.19-1.51a6.4 6.4 0 0 1-1.475-2.038A5.95 5.95 0 0 1 0 10.573Q0 9.278.547 8.08q.547-1.2 1.523-2.062a5.5 5.5 0 0 1 2.307-1.223A5.7 5.7 0 0 1 5.472 2.35 6.1 6.1 0 0 1 7.565.623 5.8 5.8 0 0 1 10.206 0q1.19 0 2.26.456a6.1 6.1 0 0 1 1.903 1.27 5.7 5.7 0 0 1 1.88-.311q1.594 0 2.95.79a6 6 0 0 1 2.165 2.159q.832 1.366.832 3.045 0 .695-.19 1.51a6.3 6.3 0 0 1 1.475 2.062q.523 1.15.523 2.422a5.9 5.9 0 0 1-.547 2.493q-.547 1.2-1.546 2.086a5.4 5.4 0 0 1-2.284 1.199 5.56 5.56 0 0 1-1.118 2.445 5.9 5.9 0 0 1-2.07 1.727 5.8 5.8 0 0 1-2.64.623m-5.876-2.997q1.19 0 2.07-.504l4.472-2.589a.53.53 0 0 0 .238-.455v-2.062L8.945 18.7a.96.96 0 0 1-1.047 0l-4.496-2.613a.7.7 0 0 1-.024.168v.287q0 1.224.571 2.254a4.24 4.24 0 0 0 1.642 1.583q1.047.6 2.331.599m.238-3.908a.6.6 0 0 0 .262.072q.118 0 .238-.072l1.784-1.031-5.734-3.357q-.522-.312-.523-.935V6.545a4.3 4.3 0 0 0-1.903 1.63 4.25 4.25 0 0 0-.714 2.398q0 1.176.595 2.254.594 1.08 1.546 1.63zm5.638 5.323q1.26 0 2.284-.576a4.3 4.3 0 0 0 1.618-1.582q.595-1.008.595-2.254v-5.179a.47.47 0 0 0-.238-.431l-1.808-1.055v6.689q0 .624-.524.935l-4.496 2.613a4.3 4.3 0 0 0 2.57.84m.904-8.776v-3.26l-2.688-1.535-2.712 1.535v3.26l2.712 1.535zM7.756 5.97q0-.623.523-.935l4.496-2.613a4.3 4.3 0 0 0-2.569-.84q-1.26 0-2.284.576A4.3 4.3 0 0 0 6.304 3.74q-.57 1.008-.57 2.254v5.155q0 .287.237.455l1.785 1.055zM19.84 17.43a4.16 4.16 0 0 0 1.88-1.63 4.33 4.33 0 0 0 .713-2.397q0-1.176-.595-2.254-.594-1.08-1.546-1.63l-4.449-2.59q-.143-.096-.261-.072a.46.46 0 0 0-.238.072L13.56 7.936l5.758 3.38a.9.9 0 0 1 .38.384q.143.216.143.528zM15.059 5.25q.524-.335 1.047 0l4.52 2.662V7.48q0-1.15-.57-2.181A4.14 4.14 0 0 0 18.46 3.62q-1.023-.623-2.379-.623-1.19 0-2.07.503L9.54 6.09a.53.53 0 0 0-.238.455v2.062z\"\n    fill=\"white\"\n  />\n</svg>";
+const cursorIcon="<svg width=\"20\" height=\"20\" aria-hidden=\"true\" focusable=\"false\" fill=\"none\" viewBox=\"0 0 512 512\" xmlns=\"http://www.w3.org/2000/svg\"><clipPath id=\"prnext-dev-cursor-cutout\"><path d=\"m96 73h320.735v365.65h-320.735z\"/></clipPath><path d=\"m512.001 325.499c0 7.124 0 14.24-.041 21.364-.035 5.999-.103 11.998-.268 17.99-.356 13.068-1.124 26.245-3.448 39.169-2.359 13.109-6.205 25.306-12.266 37.222-5.958 11.703-13.746 22.419-23.029 31.709-9.29 9.291-20 17.072-31.71 23.03-11.909 6.061-24.113 9.907-37.222 12.266-12.923 2.324-26.101 3.092-39.169 3.448-5.999.165-11.991.233-17.99.268-7.123.048-14.24.041-21.364.041h-139c-7.124 0-14.24 0-21.364-.041-5.999-.035-11.998-.103-17.99-.268-13.068-.356-26.245-1.124-39.169-3.448-13.109-2.359-25.306-6.205-37.2219-12.266-11.7034-5.958-22.4195-13.746-31.7095-23.03-9.29-9.29-17.0717-19.999-23.0296-31.709-6.06082-11.909-9.90709-24.113-12.26559-37.222-2.32422-12.924-3.092104-26.101-3.448621-39.169-.164547-5.999-.2331075-11.991-.267388-17.99-.02742444-7.124-.02742444-14.24-.02742444-21.364v-139c0-7.124 0-14.24.04113664-21.364.0342805-5.999.1028418-11.998.2673878-17.99.356517-13.068 1.124399-26.245 3.448619-39.169 2.3585-13.1091 6.20477-25.3061 12.26558-37.222 5.9579-11.7034 13.7465-22.4195 23.0296-31.7095 9.2901-9.29 19.9993-17.0717 31.7095-23.0296 11.9091-6.06082 24.1129-9.90709 37.2222-12.26559 12.923-2.32422 26.101-3.092101 39.168-3.448618 6-.164547 11.992-.2331075 17.991-.2673881 7.117-.03428046 14.233-.03428046 21.357-.03428046h139c7.124 0 14.24 0 21.364.04113656 5.999.0342806 11.998.102842 17.99.267388 13.068.356517 26.245 1.124402 39.169 3.448622 13.109 2.3585 25.306 6.20477 37.222 12.26553 11.703 5.958 22.419 13.7465 31.709 23.0297 9.29 9.29 17.072 19.9992 23.03 31.7094 6.061 11.9091 9.907 24.113 12.266 37.2222 2.324 12.923 3.092 26.101 3.448 39.169.165 5.999.233 11.991.268 17.99.048 7.123.041 14.24.041 21.364v139z\" fill=\"#14120b\"/><path d=\"m186.501 3.99902h139c7.125 0 14.231-.00004 21.341.04102 5.985.0342 11.952.10221 17.903.26562h.001c13.003.35475 25.943 1.11709 38.569 3.3877 12.775 2.29828 24.592 6.03144 36.118 11.89354v-.001c10.973 5.5867 21.052 12.8384 29.848 21.4571l.847.8379c8.993 8.993 16.525 19.3593 22.292 30.6933l3.565-1.8135-3.565 1.8145c5.678 11.1575 9.36 22.6024 11.674 34.9208l.219 1.195c2.129 11.837 2.932 23.95 3.316 36.132l.072 2.438c.164 5.958.232 11.919.266 17.904v.004c.048 7.107.041 14.207.041 21.337v129.344l-.007-.007v9.656c0 7.125 0 14.231-.041 21.341-.034 5.985-.102 11.952-.266 17.903v.001c-.354 13.003-1.117 25.944-3.387 38.569-2.227 12.376-5.8 23.853-11.351 35.037l-.543 1.08c-5.767 11.327-13.306 21.701-22.293 30.695-8.993 8.993-19.361 16.526-30.695 22.293-11.518 5.861-23.342 9.595-36.116 11.894-11.837 2.128-23.95 2.931-36.132 3.315l-2.438.072c-5.958.164-11.919.232-17.904.266h-.004c-7.107.048-14.207.041-21.337.041h-139c-7.125 0-14.231 0-21.341-.041-5.985-.034-11.952-.102-17.903-.266h-.001c-13.003-.355-25.944-1.117-38.57-3.387-12.7742-2.299-24.5914-6.032-36.1165-11.894h.001c-10.974-5.587-21.0534-12.837-29.8496-21.456l-.8467-.838c-8.7118-8.712-16.0531-18.713-21.7461-29.634l-.5459-1.06-.544-1.081c-5.3709-10.816-8.8904-21.919-11.12983-33.84l-.21973-1.196c-2.27061-12.625-3.03294-25.566-3.38769-38.569v-.001c-.16342-5.958-.23143-11.918-.26563-17.903-.02736-7.112-.02734-14.219-.02734-21.341v-139c0-7.125-.00005-14.231.04101-21.341.0342-5.985.10222-11.952.26563-17.903v-.001c.35475-13.003 1.11699-25.944 3.38769-38.57 2.29829-12.7743 6.03159-24.5916 11.89359-36.1166l-.001-.001c5.7665-11.3269 13.3073-21.6999 22.2939-30.6934 8.9933-8.9932 19.36-16.5261 30.6944-22.2929h.0009c11.5174-5.8615 23.3407-9.59617 36.1149-11.89455 11.837-2.12878 23.951-2.93017 36.133-3.31446l2.438-.07226c5.958-.16342 11.919-.23142 17.904-.26563l-.001-.00097c7.104-.03422 14.211-.03321 21.335-.03321z\" stroke=\"#edecec\" stroke-opacity=\".2\" stroke-width=\"8\"/><g clip-path=\"url(#prnext-dev-cursor-cutout)\"><path d=\"m410.344 159.545-146.38-84.5111c-4.7-2.7145-10.5-2.7145-15.2 0l-146.373 84.5111c-3.9515 2.282-6.391 6.501-6.391 11.071v170.418c0 4.569 2.4395 8.789 6.391 11.07l146.379 84.512c4.701 2.714 10.501 2.714 15.201 0l146.38-84.512c3.951-2.281 6.391-6.501 6.391-11.07v-170.418c0-4.57-2.44-8.789-6.391-11.071zm-9.195 17.902-141.308 244.751c-.955 1.65-3.477.976-3.477-.934v-160.261c0-3.203-1.711-6.164-4.487-7.772l-138.786-80.127c-1.65-.956-.976-3.478.934-3.478h282.616c4.013 0 6.522 4.35 4.515 7.828h-.007z\" fill=\"#edecec\"/></g></svg>";
+const claudeIcon="<svg width=\"20\" height=\"20\" aria-hidden=\"true\" focusable=\"false\" viewBox=\"0 0 248 248\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M52.4285 162.873L98.7844 136.879L99.5485 134.602L98.7844 133.334H96.4921L88.7237 132.862L62.2346 132.153L39.3113 131.207L17.0249 130.026L11.4214 128.844L6.2 121.873L6.7094 118.447L11.4214 115.257L18.171 115.847L33.0711 116.911L55.485 118.447L71.6586 119.392L95.728 121.873H99.5485L100.058 120.337L98.7844 119.392L97.7656 118.447L74.5877 102.732L49.4995 86.1905L36.3823 76.62L29.3779 71.7757L25.8121 67.2858L24.2839 57.3608L30.6515 50.2716L39.3113 50.8623L41.4763 51.4531L50.2636 58.1879L68.9842 72.7209L93.4357 90.6804L97.0015 93.6343L98.4374 92.6652L98.6571 91.9801L97.0015 89.2625L83.757 65.2772L69.621 40.8192L63.2534 30.6579L61.5978 24.632C60.9565 22.1032 60.579 20.0111 60.579 17.4246L67.8381 7.49965L71.9133 6.19995L81.7193 7.49965L85.7946 11.0443L91.9074 24.9865L101.714 46.8451L116.996 76.62L121.453 85.4816L123.873 93.6343L124.764 96.1155H126.292V94.6976L127.566 77.9197L129.858 57.3608L132.15 30.8942L132.915 23.4505L136.608 14.4708L143.994 9.62643L149.725 12.344L154.437 19.0788L153.8 23.4505L150.998 41.6463L145.522 70.1215L141.957 89.2625H143.994L146.414 86.7813L156.093 74.0206L172.266 53.698L179.398 45.6635L187.803 36.802L193.152 32.5484H203.34L210.726 43.6549L207.415 55.1159L196.972 68.3492L188.312 79.5739L175.896 96.2095L168.191 109.585L168.882 110.689L170.738 110.53L198.755 104.504L213.91 101.787L231.994 98.7149L240.144 102.496L241.036 106.395L237.852 114.311L218.495 119.037L195.826 123.645L162.07 131.592L161.696 131.893L162.137 132.547L177.36 133.925L183.855 134.279H199.774L229.447 136.524L237.215 141.605L241.8 147.867L241.036 152.711L229.065 158.737L213.019 154.956L175.45 145.977L162.587 142.787H160.805V143.85L171.502 154.366L191.242 172.089L215.82 195.011L217.094 200.682L213.91 205.172L210.599 204.699L188.949 188.394L180.544 181.069L161.696 165.118H160.422V166.772L164.752 173.152L187.803 207.771L188.949 218.405L187.294 221.832L181.308 223.959L174.813 222.777L161.187 203.754L147.305 182.486L136.098 163.345L134.745 164.2L128.075 235.42L125.019 239.082L117.887 241.8L111.902 237.31L108.718 229.984L111.902 215.452L115.722 196.547L118.779 181.541L121.58 162.873L123.291 156.636L123.14 156.219L121.773 156.449L107.699 175.752L86.304 204.699L69.3663 222.777L65.291 224.431L58.2867 220.768L58.9235 214.27L62.8713 208.48L86.304 178.705L100.44 160.155L109.551 149.507L109.462 147.967L108.959 147.924L46.6977 188.512L35.6182 189.93L30.7788 185.44L31.4156 178.115L33.7079 175.752L52.4285 162.873Z\" fill=\"#D97757\"/>\n</svg>";
+const otherIcon="<svg width=\"20\" height=\"20\" aria-hidden=\"true\" focusable=\"false\" xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"m8 7-5 5 5 5m8-10 5 5-5 5m-3-14-2 18\"/></svg>";
+
+export const devAiBrands=Object.freeze([
+  Object.freeze({id:'codex',label:'Codex',caption:'CLI & VS Code',icon:codexIcon}),
+  Object.freeze({id:'cursor',label:'Cursor',caption:'Editor',icon:cursorIcon}),
+  Object.freeze({id:'claude',label:'Claude Code',caption:'CLI & editor',icon:claudeIcon}),
+]);
+export const devMcpBrand=Object.freeze({id:'other',label:'Other MCP',caption:'Manual setup',icon:otherIcon});
+export const devAiProviders=Object.freeze([...devAiBrands,devMcpBrand]);