@thomas.f/prnext 0.1.13-alpha → 0.1.15-alpha

package/README.md

@@ -1,51 +1,21 @@
-<a href="https://prnext.dev"><img src="https://prnext.dev/favicon.svg" alt="PRNext logo" width="80" height="80"></a>
+<p align="center">
+  <a href="https://prnext.dev">
+    <img src="https://raw.githubusercontent.com/Lorkydey/PRNext/main/.github/assets/prnext-logo.svg" alt="PRNext logo" width="112" height="112">
+  </a>
+</p>
 
-# PRNext
+<h1 align="center">PRNext</h1>
 
-[Website](https://prnext.dev) · [npm](https://www.npmjs.com/package/@thomas.f/prnext) · [GitHub](https://github.com/Lorkydey/PRNext) · [X / @PRNextdev](https://x.com/PRNextdev) · [Report an issue](https://github.com/Lorkydey/PRNext/issues)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@thomas.f/prnext"><img src="https://img.shields.io/npm/v/%40thomas.f%2Fprnext/alpha?style=for-the-badge&amp;label=npm&amp;labelColor=161b22&amp;color=007ec6" alt="Current npm alpha version" height="28" align="absmiddle"></a> &nbsp;
+  <a href="https://github.com/Lorkydey/PRNext/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Lorkydey/PRNext?style=for-the-badge&amp;label=license&amp;labelColor=161b22&amp;color=98d6ac" alt="MIT License" height="28" align="absmiddle"></a> &nbsp;
+  <a href="https://x.com/PRNextdev"><img src="https://img.shields.io/badge/-%40PRNextdev-171717?style=for-the-badge&amp;logo=x&amp;logoColor=white" alt="Follow @PRNextdev on X" height="28" align="absmiddle"></a>
+</p>
 
-A Rust-powered runtime for Next.js projects, with React and npm modules running on Node.js.
+A Rust-powered web runtime with React rendering on Node.js and a static adapter for completed browser builds.
 
 > **Very early alpha.** Built for experimentation and feedback. Next.js compatibility is partial; expect bugs, missing features and breaking changes.
 
-## Latest update
-
-**0.1.13-alpha — worker lifecycle, streaming and routing.** Lower Linux production-launcher overhead, parent-death containment for Linux workers, and earlier release of completed RSC response resources while background cache work remains supervised. Streaming API and middleware responses reuse their inactivity timer, preserving timeout and cancellation behavior. Ready response producers yield after bounded batches, including empty chunks, so network events and cancellation timers can run. Profile admission, V8 and idle policies remain distinct; see the runtime profile notes below.
-
-The source candidate reuses immutable production App Router routing plans, decodes the destination pathname once per request and reduces temporary segment arrays. Component exports and configuration remain live; dynamic output and request parameters are not cached. Rebuild to enable these plans; older/mutable routing trees and development retain the compatible live traversal. These changes do not establish a general HTTP performance advantage over Next.js.
-
-Client cancellations retain healthy Node hosts; worker retirement protects tracked finalization; filesystem and proxy overload return explicit, noncacheable 503 responses. Clean installs and runtime/native/build consistency checks remain part of the release path. Rebuild dynamic applications with `prnext build` after upgrading, then restart them.
-
-Shutdown now drains tracked worker and ISR work before closing private cache services. Standalone service shutdown shares a 30-second deadline between HTTP responses and background work. Ordinary Host sleep and capacity eviction allow up to 300 seconds of tracked work, covering the supported `maxDuration` range, followed by process cleanup. Global Host shutdown remains bounded to 35 seconds; memory-budget violations retain their shorter enforced stop. Monitoring continues while applications drain. This protects supported `after()` callbacks, not arbitrary timers or durable jobs.
-
-The October 15 comparison of a frozen local candidate with Next.js 16.4.1 measured `balanced` SSR at 365 vs 281 req/s on Windows and 218 vs 158 on Linux, with cumulative server RSS of 182 vs 362 MiB and 149 vs 247 MiB respectively. Production, one server CPU, 64 connections, five 30-second runs after 10-second warmups, the same 100-row application, no dynamic page cache. These measurements precede the final shutdown fix and are not final-package performance certification. TanStack Start was faster on the App Router-equivalent SSR, streaming and JSON workloads; PRNext does not claim a universal performance lead. See the [release methodology and limits](https://github.com/Lorkydey/PRNext/blob/main/RELEASE.md#performance-evidence).
-
-The experimental eight-app `balanced`/1 GiB Windows commit configuration with `NODE_OPTIONS=--max-semi-space-size=1` still has a reproduced allocation-failure regression relative to V5. It is not a supported density target and is not fixed. Defaults remain `start=balanced` and `host=memory`. Compatibility remains partial, including the compiler and TypeScript limits below.
-
-<details>
-<summary><strong>0.1.1-alpha · October 8, 2026 · Features & fixes</strong></summary>
-
-**README update:** `0.1.11-alpha` updates the README only; runtime features and fixes remain those of `0.1.1-alpha`.
-
-### Added
-
-- **Windows x64 & ARM64:** native packages alongside macOS and Linux glibc support.
-- **Persistent apps:** background processes, crash recovery, rotating logs, health-checked replacements and optional restoration at login.
-- **Multi-app hosting:** hostname routing, on-demand startup, idle sleep and sampled memory budgets.
-- **Migration checks:** source audits and optional GET response comparisons with `migrate --check`.
-- **Inspector:** opt-in route, cache and request timing diagnostics.
-
-### Fixed
-
-- Standalone dependency tracing for Windows drives, scoped packages and workspace aliases.
-- Development process shutdown and file replacement on Windows.
-- Cold-worker connection bursts on macOS.
-- Windows package publishing and portable `prnext` migration scripts.
-
-</details>
-
-[Full changelog](https://github.com/Lorkydey/PRNext/blob/main/CHANGELOG.md)
-
 ## Install & upgrade
 
 Node.js **22+** · Windows, macOS and Linux glibc · x64 and ARM64
@@ -331,6 +301,27 @@ Under concurrent streaming, `memory` used 179 MiB versus 207 MiB for `balanced`,
 
 ## Guides
 
+### Build adapters
+
+PRNext keeps its React/Next-convention build as the default. The source candidate
+also imports static browser builds produced by Vite or another framework:
+
+```sh
+npm run build
+npx --no-install prnext build --adapter static --from dist --spa
+npx --no-install prnext start
+```
+
+Use `--spa` only for client-side routing. Omit it for a multi-page site. PRNext
+imports the completed public files; it does not compile Vue/Svelte source or run
+another framework's SSR server. Static requests require no Node render worker.
+This adapter needs the updated native binary built from the same source candidate;
+it is not part of the previously published alpha package.
+
+Every new build writes a versioned `build-output.json`. Inspect it with
+`prnext output --json`. See the [adapter contract](packages/prnext/build/ADAPTERS.md)
+and [compatibility scope](COMPATIBILITY.md) for supported inputs and boundaries.
+
 <details>
 <summary><strong>Deploy to PRNext Cloud (local development)</strong></summary>
 
@@ -423,10 +414,24 @@ prnext start ./my-app --inspect
 # In another terminal, after visiting the application:
 prnext inspect ./my-app
 prnext inspect ./my-app --json
+prnext inspect ./my-app --otlp > metrics.json
 ```
 
 The inspector explains static, dynamic and partially prerendered routes using build metadata, including observed App prerendering bailouts and Pages data hooks. Opt-in measurements show native HTTP timings, fetch destinations and timings, native data cache hits/misses/stale reads, bypass reasons and successful tag/path invalidations. A custom cache handler is identified as a delegation; its internal hit rate is not inferred. Native page-file cache decisions and client router caching are not counted as data-cache hits.
 
+The summary adds sampled HTTP p50/p95, server errors, worker startup p95, current
+worker queue/activity and recent Node worker RSS. Missing or stale resource samples
+are shown as unavailable, never as zero. RSS excludes the native server; worker
+threads sharing a PID are counted once. `start --inspect` also enables bounded native
+counter snapshots. These opt-in diagnostics do not change normal serving defaults.
+
+`inspect --otlp` writes an OTLP/JSON Metrics payload for a bounded local sample.
+The custom `prnext.http.response.headers.duration` histogram uses seconds and stops
+at response headers, excluding streaming body time. It is deliberately not named
+`http.server.request.duration`. Samples can span sessions and overlap repeated
+exports; this is a diagnostic snapshot, not a continuous traffic or billing counter.
+No collector connection or public diagnostics endpoint is enabled automatically.
+
 Timings end when headers are ready, so streaming body time is excluded. Samples are bounded, can span process sessions, and are written under the app's `.prnext-cache/inspect` directory. Request bodies, headers, cookies, URL queries and credentials are omitted; runtime tag/path identifiers are hashed consistently. Logs retain at most 1 MiB per segment plus a previous segment, with old process sessions pruned. Under load, diagnostics may drop samples. `--inspect` also works with `prnext dev`; standalone/native launches can set `PRNEXT_INSPECT_DIR` explicitly. No public diagnostic endpoint is added.
 
 </details>
@@ -545,6 +550,12 @@ For source builds, `cargo build --release --locked --features gzip-zlib-rs` enab
 
 </details>
 
+## Contributing
+
+Read the [contribution guide](https://github.com/Lorkydey/PRNext/blob/main/CONTRIBUTING.md),
+[Code of Conduct](https://github.com/Lorkydey/PRNext/blob/main/CODE_OF_CONDUCT.md)
+and [security policy](https://github.com/Lorkydey/PRNext/blob/main/SECURITY.md).
+
 <details>
 <summary><strong>License & credits</strong></summary>
 

package/build/ADAPTERS.md

@@ -0,0 +1,121 @@
+# Build output contract v1
+
+This contract describes the adapter and entrypoints of a completed PRNext build.
+It is distinct from `runtime-contract.json`, which fingerprints the React worker
+implementation and enforces lifecycle guarantees. It is not a signature or an
+integrity check for arbitrary files, and build artifacts must remain trusted.
+
+## Output selection
+
+The project-level `.prnext-output.json` selects a relative build directory, usually
+`.prnext`. Paths in `build-output.json` are relative to that directory. The runtime
+does not evaluate project configuration to start a completed build.
+
+Every new React and static build emits all seven fields below. Unknown fields,
+versions, adapters, entrypoints and inconsistent build identities are rejected by
+the native server before listening. Existing React builds without this metadata
+retain their original runtime-contract checks. Static builds require it.
+
+```json
+{
+  "version": 1,
+  "adapter": "react",
+  "buildId": "a-build-identifier",
+  "manifest": "manifest.json",
+  "assets": "assets",
+  "server": {
+    "entry": "runtime/worker.mjs",
+    "runtimeContract": "runtime-contract.json"
+  },
+  "fallback": null
+}
+```
+
+`buildId` must match the manifest and contain 1–128 ASCII letters, digits,
+underscores or hyphens. Metadata is limited to 64 KiB. Entry paths are fixed in
+v1; they cannot select an arbitrary executable or escape the build directory.
+The React manifest continues to describe routing, caching and rendering details;
+its implementation-specific fields are not made stable by this public envelope.
+
+## Static adapter
+
+Build the application with its own tool, then import **only** its public browser
+output. Vite's default output is `dist`; see its [deployment guide](https://vite.dev/guide/static-deploy.html).
+
+```sh
+npm run build
+prnext build --adapter static --from dist
+prnext output --json
+prnext start --hostname 127.0.0.1 --port 3000
+```
+
+Programmatic equivalent:
+
+```js
+import { build, buildStatic, readBuildOutput } from '@thomas.f/prnext';
+await build(projectRoot, { adapter: 'static', from: 'dist', spa: true });
+// Or: await buildStatic(projectRoot, { from: 'dist', spa: true });
+const output = await readBuildOutput(buildDirectory);
+```
+
+The static envelope has `adapter: "static"`, `assets: "static"`, `server: null`
+and `fallback: null`. With `--spa`, fallback is `"index.html"`. Its manifest has:
+
+```json
+{
+  "version": 1,
+  "buildId": "a-build-identifier",
+  "config": { "staticOnly": true, "staticFallback": false, "compress": true, "poweredByHeader": true },
+  "routes": [],
+  "prerendered": [
+    { "path": "/", "file": "static/index.html", "revalidate": false }
+  ]
+}
+```
+
+Every imported file has an exact, URL-encoded path in `prerendered`; `file` stays
+relative to the build. `/index.html` also maps to `/`, `/docs/index.html` to `/docs`,
+and `/about.html` to `/about`. Conflicting aliases fail the import. Normal native
+trailing-slash redirects apply. No server routes, middleware, ISR or cache handler
+can be declared. The project's separate `public/` directory is not served.
+
+With SPA fallback enabled, unmatched GET/HEAD requests that explicitly accept
+`text/html` can receive the root index. Existing files and pages take precedence.
+Missing file extensions, `/api/*`, hidden paths and framework transport paths do
+not fall back. JSON requests and POSTs never receive an SPA fallback. Apps using
+dotted client route names need explicit HTML output for those URLs. Configure the
+source builder's asset base for its deployed URL; the adapter does not rewrite JS
+or HTML assets or infer subpath hosting configuration.
+
+The source directory must be inside the project, separate from the destination,
+with real directories and files. Symlinks, dotfiles other than a root `.well-known`
+tree, `node_modules`, reserved `_next`/`_prnext` paths and a root `server` directory
+are rejected. Limits are 20,000 files, 512 MiB total and 64 directory levels.
+Environment files and server outputs must never be placed in public input.
+
+Imports use a staging directory and publish the manifest, files and output pointer
+together. A validation/copy failure leaves the previous build intact. Source files
+and configuration are untouched. A project lock excludes concurrent React builds
+and static imports, including separate processes and canonical path aliases.
+Another active build fails clearly; a dead local owner is recovered. A lock from
+another host, an unverifiable owner or an interrupted lock recovery fails closed;
+check `.prnext-build.lock` manually only after confirming no build is active.
+Finish the source framework build before importing its files.
+
+Compressible files are precompressed with the same bounded gzip pipeline as React
+builds. Source files are unchanged. Existing gzip sidecars must decode exactly to
+their source; a mismatched sidecar fails the import and preserves the last build.
+
+Serve with the updated native binary from this source candidate. Node can run the
+CLI to build/start, but no Node worker or React installation is required to serve
+static requests. `prnext host` can validate and host these completed artifacts.
+Cloud source-build auto-detection is a separate integration; this change does not
+change existing PRNext Host projects or enable generic SSR hosting.
+
+## Extending adapters
+
+The current adapter names are `react` and `static`. Unknown adapters fail rather
+than being silently interpreted as React. Add a new adapter only with a documented
+runtime model and integration tests. A future generic Node SSR adapter needs its
+own request/response, streaming, cancellation, crash and shutdown contract; a
+`server` path alone does not implement those guarantees.

package/build/app.mjs

@@ -391,6 +391,9 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
       define:{...common.define,'process.env.NEXT_RUNTIME':'"nodejs"'},
       chunkNames: 'chunk-[hash]', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" },
       target: 'node22', conditions: mode === 'rsc' ? ['react-server', 'node'] : ['node'], sourcemap: dev,
+      // Dual-format packages can retain use-client boundaries only in their
+      // ESM distribution (a bundled CommonJS entry can erase those directives).
+      mainFields: mode === 'rsc' ? ['module', 'main'] : ['main', 'module'],
       plugins: [moduleResolutionPlugin(moduleResolution, project.root), images.plugin(), fonts.plugin(), graphPlugin(mode, { styleTarget }), npmPackagesPlugin({ projectRoot: project.root, serverExternalPackages }), nativePackages.plugin(mode), cssModules.plugin(false)],
         });
         if (nativePackages.version !== nativeVersion) {

package/build/build-lock.mjs

@@ -0,0 +1,71 @@
+import { mkdir, writeFile, rename, rm, realpath, lstat, open } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import path from 'node:path';
+
+const LOCK = '.prnext-build.lock';
+const busy = message => Object.assign(new Error(message), { code: 'PRNEXT_BUILD_LOCKED' });
+function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; }
+}
+async function owner(directory) {
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw busy('The build lock is not a real directory. Check .prnext-build.lock before retrying.');
+  const file = await open(path.join(directory, 'owner.json'), 'r');
+  try {
+    if ((await file.stat()).size > 4096) throw new Error('oversized owner');
+    const value = JSON.parse(await file.readFile('utf8'));
+    if (!Number.isSafeInteger(value.pid) || value.pid < 1 || typeof value.host !== 'string' || !/^[a-f0-9-]{36}$/.test(value.token)) throw new Error('invalid owner');
+    return value;
+  } finally { await file.close(); }
+}
+
+/** One publisher per canonical project, covering React and direct static imports. */
+export async function withBuildLock(directory, action) {
+  const root = await realpath(directory), lock = path.join(root, LOCK);
+  const identity = { pid: process.pid, host: hostname(), token: randomUUID(), createdAt: new Date().toISOString() };
+  const prepared = path.join(root, `.prnext-lock-${identity.token}`);
+  await mkdir(prepared, { mode: 0o700 });
+  try {
+    await writeFile(path.join(prepared, 'owner.json'), JSON.stringify(identity), { flag: 'wx', mode: 0o600 });
+    for (let attempt = 0; ; attempt++) {
+      try { await rename(prepared, lock); break; }
+      catch (error) {
+        if (!['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(error.code)) throw error;
+        let previous;
+        try { previous = await owner(lock); }
+        catch (cause) {
+          if (cause.code === 'ENOENT' && attempt < 8) continue;
+          throw busy('Cannot verify the build lock. Check .prnext-build.lock before retrying.');
+        }
+        if (previous.host !== identity.host || alive(previous.pid)) throw busy(`A build is already running for this project (PID ${previous.pid}). Wait for it to finish.`);
+        // Exactly one contender can recover this generation. Never delete a lock
+        // merely because it is old: long builds and suspended processes are valid.
+        let claim;
+        try { claim = await open(path.join(lock, 'recovery'), 'wx', 0o600); }
+        catch (cause) {
+          if (cause.code === 'ENOENT' && attempt < 8) continue;
+          throw busy('Build lock recovery is in progress. Retry shortly; if recovery was interrupted, check .prnext-build.lock manually.');
+        }
+        const retired = path.join(root, `.prnext-lock-retired-${identity.token}`);
+        try {
+          await claim.writeFile(JSON.stringify(identity)); await claim.close(); claim = null;
+          const current = await owner(lock);
+          if (current.token !== previous.token) {
+            // Do not unlink through this path: the new owner can release and
+            // another generation can appear between our read and the unlink.
+            throw busy('The build lock changed during recovery. Retry the build.');
+          }
+          await rename(lock, retired);
+          await rm(retired, { recursive: true });
+        } finally { await claim?.close(); }
+      }
+    }
+    try { return await action(root); }
+    finally {
+      // Ownership must still match before releasing a lock.
+      if ((await owner(lock)).token === identity.token) await rm(lock, { recursive: true });
+    }
+  } finally { await rm(prepared, { recursive: true, force: true }); }
+}

package/build/index.mjs

@@ -1,5 +1,6 @@
 import { rename } from '../runtime/fs.mjs';
 import { writeRuntimeContract } from './runtime-contract.mjs';
+import { writeBuildOutput } from './output-contract.mjs';
 import { bundleRuntime } from './bundle-runtime.mjs';
 import {frameworkImportName, frameworkRuntimeImportPattern} from './framework-imports.mjs';
 import { expandLocales, localizedStaticPaths } from './i18n.mjs';
@@ -20,6 +21,7 @@ import { createImages } from './images.mjs';
 import { compileApp } from './app.mjs';
 import { prerenderApp } from './app-static.mjs';
 import { precompressBuild } from './precompress.mjs';
+import { withBuildLock } from './build-lock.mjs';
 import { loadProjectConfig, defineEnvironment, generateBuildId, publicAssetBase } from './config.mjs';
 import { compileCustomRoutes } from './custom-routes.mjs';
 import { compileMiddleware } from './middleware.mjs';
@@ -186,10 +188,13 @@ let buildQueue = Promise.resolve();
 /** Isolate process.env between programmatic builds, including simultaneous calls. */
 export function build(projectRoot, options = {}) {
   const task = buildQueue.then(async () => {
+    if (options.adapter === 'static') return (await import('./static-adapter.mjs')).buildStatic(projectRoot, options);
+    if (options.adapter !== undefined && options.adapter !== 'react') throw new Error(`Unknown PRNext adapter: ${options.adapter}`);
+    if (options.from !== undefined || options.spa !== undefined) throw new Error('from and spa are only supported by the static adapter.');
     const restore = snapshotEnvConfig();
     const envMode = options.envMode || (process.env.NODE_ENV === 'test' ? 'test' : options.dev ? 'development' : 'production');
     process.env.NODE_ENV = options.dev ? 'development' : 'production';
-    try { return await withCompilation(() => buildProject(projectRoot, { ...options, envMode })); }
+    try { return await withBuildLock(projectRoot, root => withCompilation(() => buildProject(root, { ...options, envMode }))); }
     finally { restore(); }
   });
   buildQueue = task.catch(() => {});
@@ -335,6 +340,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     }
     await writeRuntimeContract(stage);
     await writeFile(path.join(stage, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+    await writeBuildOutput(stage, manifest);
     if (config.compress) await precompressBuild(stage, manifest, {cacheDirectory:path.join(project.root,'.prnext-cache/precompress-v1')});
     if (config.output === 'standalone' && !dev) await (await import('./standalone-runner.mjs')).prepareStandalone({ projectRoot: project.root, stage, manifest, config });
     const exporting = config.output === 'export' && !dev ? await import('./static-export.mjs') : null;

package/build/inspect.mjs

@@ -1,6 +1,8 @@
-import { readFile, readdir, stat } from 'node:fs/promises';
+import { readFile, readdir, stat, open } from 'node:fs/promises';
 import path from 'node:path';
 import { readBuildDirectory } from '../runtime/build-directory.mjs';
+import { summarizeDiagnostics, inspectionMetrics } from './inspection-summary.mjs';
+export { inspectionMetrics };
 
 export function explainRoute(route, manifest) {
   const seeds = manifest.prerendered.filter(seed => seed.routeId === route.id || (!seed.routeId && seed.path === route.pattern));
@@ -27,6 +29,18 @@ export async function inspectProject(directory) {
   try { manifest = JSON.parse(await readFile(path.join(root, output, 'manifest.json'), 'utf8')); }
   catch (error) { throw new Error(`Cannot read a build in ${root}. Run prn build first.`, { cause: error }); }
   const folder = path.join(root, '.prnext-cache/inspect');
+  const runtime = [];
+  for (const name of (await readdir(folder).catch(error => {if(error.code==='ENOENT')return [];throw error;})).filter(name => /^metrics-\d+\.jsonl$/.test(name)).slice(-8)) {
+    let file;
+    try {
+      file = await open(path.join(folder,name),'r');
+      const info = await file.stat(), bytes = Buffer.alloc(Math.min(info.size,65536));
+      await file.read(bytes,0,bytes.length,Math.max(0,info.size-bytes.length));
+      for (const line of bytes.toString().split('\n').reverse()) {
+        try { const value=JSON.parse(line);if(Number.isFinite(value.unixMs)&&value.workers){runtime.push(value);break;} } catch {}
+      }
+    } catch {} finally {await file?.close();}
+  }
   let names = [];
   try { names = (await readdir(folder)).filter(name => /^(?:worker-\d+-\d+|native-\d+)\.jsonl(?:\.1)?$/.test(name)); }
   catch (error) { if (error.code !== 'ENOENT') throw error; }
@@ -50,7 +64,7 @@ export async function inspectProject(directory) {
     durations.sort((a, b) => a - b);
     return { ...group, ...(durations.length ? { meanMs: Math.round(durations.reduce((a, b) => a + b, 0) / durations.length * 100) / 100, p95Ms: durations[Math.ceil(durations.length * .95) - 1], maxMs: durations.at(-1) } : {}) };
   }).sort((a, b) => (b.p95Ms || 0) - (a.p95Ms || 0));
-  return { version: 1, root, buildId: manifest.buildId, routes: manifest.routes.filter(route => !route.internal).map(route => explainRoute(route, manifest)),
+  return { version: 1, root, buildId: manifest.buildId, ...summarizeDiagnostics(recent,runtime), routes: manifest.routes.filter(route => !route.internal).map(route => explainRoute(route, manifest)),
     measurements, cacheEntries: [...entries.values()].slice(-100), invalidations: recent.filter(event => event.type === 'invalidation').slice(-50), dynamicUsage: recent.filter(event => event.type === 'dynamic').slice(-50),
     sample: { events: recent.length, from: recent[0]?.time, to: recent.at(-1)?.time },
     notes: ['Enable measurements with prn start --inspect (or prn dev --inspect), visit routes, then run prn inspect again.',
@@ -59,6 +73,10 @@ export async function inspectProject(directory) {
 }
 export function printInspection(report) {
   console.log(`PRNext inspector: ${report.root}`);
+  console.log(`Recorded sample: ${report.summary.requests} HTTP requests; p50 ${report.summary.p50Ms ?? 'n/a'} ms; p95 ${report.summary.p95Ms ?? 'n/a'} ms (response headers); ${report.summary.errors} server errors.`);
+  if(report.summary.wakeP95Ms !== null) console.log(`Worker startup p95: ${report.summary.wakeP95Ms} ms.`);
+  if(report.summary.workerRssBytes !== null) console.log(`Latest recorded worker RSS: ${(report.summary.workerRssBytes/1048576).toFixed(1)} MiB. Native server memory is not included.`);
+  for(const finding of report.findings)console.log(`${finding.level.toUpperCase()}: ${finding.message} ${finding.action}`);
   for (const route of report.routes) console.log(`${route.mode.padEnd(13)} ${route.pattern}\n  ${route.reasons.join('; ') || `${route.prerenderedPaths} prerendered path(s); revalidate: ${route.revalidate.join(', ') || 'on demand'}`}`);
   for (const item of report.measurements) console.log(`${item.type.toUpperCase()} ${item.route}${item.destination ? ' -> ' + item.destination : ''}: ${item.count} sample(s)${item.state ? ', ' + item.state : ''}${item.reason ? ' (' + item.reason + ')' : ''}${item.p95Ms !== undefined ? ', p95 ' + item.p95Ms.toFixed(2) + ' ms' : ''}, ${item.errors} error(s)`);
   for (const event of report.invalidations) console.log(`INVALIDATION ${event.route}: ${event.mode}; tags ${(event.tags || []).join(', ') || 'none'}; paths ${(event.paths || []).join(', ') || 'none'}`);

package/build/inspection-summary.mjs

@@ -0,0 +1,37 @@
+const quantile = (values, q) => values.length ? Math.round([...values].sort((a,b)=>a-b)[Math.ceil(values.length*q)-1]*100)/100 : null;
+const durations = events => events.map(e=>e.durationMs).filter(v=>Number.isFinite(v)&&v>=0);
+export function summarizeDiagnostics(events, snapshots = []) {
+  const http=events.filter(e=>e.type==='http'), times=durations(http);
+  const wake=durations(events.filter(e=>e.type==='wake'&&e.phase==='node-ready'));
+  const processes=new Map();
+  for(const event of events)if(event.type==='process'&&Number.isSafeInteger(event.pid)&&Number.isFinite(event.rssBytes)&&event.rssBytes>=0)processes.set(event.pid,event);
+  const last=snapshots.sort((a,b)=>b.unixMs-a.unixMs)[0];
+  const current=last&&Date.now()-last.unixMs<30000&&Date.now()>=last.unixMs;
+  const rss=[...processes.values()].filter(e=>Date.now()-e.time<30000&&Date.now()>=e.time);
+  const summary={requests:http.length,errors:http.filter(e=>e.status>=500).length,p50Ms:quantile(times,.5),p95Ms:quantile(times,.95),wakeP95Ms:quantile(wake,.95),workerRssBytes:rss.length?rss.reduce((n,e)=>n+e.rssBytes,0):null,
+    queuedJobs:current?last.workers.queuedJobs??null:null,activeJobs:current?last.workers.activeJobs??null:null, runtimeSampleAt:last?.unixMs??null};
+  const findings=[];
+  if(!http.length)findings.push({level:'info',code:'NO_SAMPLE',message:'No HTTP sample recorded.',action:'Start with --inspect, visit the site and run inspect again.'});
+  if(summary.queuedJobs>0)findings.push({level:'warning',code:'WORKER_QUEUE',message:`${summary.queuedJobs} jobs are waiting for a worker.`,action:'Check slow routes and available CPU/RAM before increasing concurrency.'});
+  if(summary.p95Ms>=1000)findings.push({level:'warning',code:'SLOW_HEADERS',message:'The slowest 5% of recorded responses take at least one second to prepare headers.',action:'Inspect route and fetch timings below; this includes queueing and startup.'});
+  if(summary.errors)findings.push({level:'warning',code:'SERVER_ERRORS',message:`${summary.errors} recorded requests returned a server error.`,action:'Check application logs for the same sample period.'});
+  if(summary.wakeP95Ms>=1000)findings.push({level:'info',code:'SLOW_WAKE',message:'Recorded worker startup p95 exceeds one second.',action:'Review startup imports or use keep-warm if the extra memory is acceptable.'});
+  return {summary,findings,metricSample:http.filter(e=>Number.isFinite(e.durationMs)&&e.durationMs>=0&&e.durationMs<=86400000&&Number.isSafeInteger(e.time)&&e.time>=0&&e.time<=18446744073709).map(e=>({route:typeof e.route==='string'?e.route.slice(0,256):'<unmatched>',method:/^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|CONNECT|TRACE)$/.test(e.method)?e.method:'_OTHER',durationMs:e.durationMs,time:e.time}))};
+}
+
+/** OTLP/JSON Metrics export of a bounded local sample, never a complete traffic counter. */
+export function inspectionMetrics(report) {
+  const bounds=[.001,.005,.01,.025,.05,.1,.25,.5,1,2.5,5,10], groups=new Map();
+  for(const event of report.metricSample||[]) {
+    const key=JSON.stringify([event.route,event.method]);
+    if(!groups.has(key))groups.set(key,{route:event.route,method:event.method,values:[],start:event.time,end:event.time});
+    const group=groups.get(key);group.values.push(event.durationMs/1000);group.start=Math.min(group.start,event.time);group.end=Math.max(group.end,event.time);
+  }
+  const dataPoints=[...groups.values()].map(group=>{
+    const buckets=Array(bounds.length+1).fill(0);
+    for(const value of group.values){const index=bounds.findIndex(bound=>value<=bound);buckets[index<0?bounds.length:index]++;}
+    return {attributes:[{key:'http.route',value:{stringValue:group.route}},{key:'http.request.method',value:{stringValue:group.method}}],
+      startTimeUnixNano:String(BigInt(Math.trunc(group.start))*1000000n),timeUnixNano:String(BigInt(Math.trunc(group.end))*1000000n),count:String(group.values.length),sum:group.values.reduce((a,b)=>a+b,0),min:Math.min(...group.values),max:Math.max(...group.values),explicitBounds:bounds,bucketCounts:buckets.map(String)};
+  });
+  return {resourceMetrics:[{resource:{attributes:[{key:'service.name',value:{stringValue:'prnext'}},{key:'prnext.inspect.sampled',value:{boolValue:true}}]},scopeMetrics:[{scope:{name:'prnext.inspect',version:'1'},metrics:[{name:'prnext.http.response.headers.duration',description:'Bounded diagnostic sample of time until response headers; excludes response body streaming.',unit:'s',histogram:{aggregationTemporality:1,dataPoints}}]}]}]};
+}

package/build/og.mjs

@@ -1,14 +1,8 @@
-import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { createRequire } from 'node:module';
+import { cp, mkdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 export async function prepareImageResponse(stage) {
-  const directory = path.dirname(createRequire(import.meta.url).resolve('@vercel/og'));
   const target = path.join(stage, 'runtime/og');
   await mkdir(target, { recursive: true });
-  await writeFile(path.join(target, 'index.node.mjs'), `import {createRequire as __prnextRequire} from 'node:module';import {fileURLToPath as __prnextFile} from 'node:url';import {dirname as __prnextDir} from 'node:path';const require=__prnextRequire(import.meta.url),__filename=__prnextFile(import.meta.url),__dirname=__prnextDir(__filename);\n` + await readFile(path.join(directory, 'index.node.js'), 'utf8'));
-  for (const name of ['Geist-Regular.ttf', 'resvg.wasm']) await cp(path.join(directory, name), path.join(target, name));
-  await cp(path.join(directory, '../LICENSE'), path.join(target, 'LICENSE'));
-  await writeFile(path.join(target, 'NOTICE.txt'), 'Image renderer: @vercel/og 1.0.3 (https://github.com/vercel/og). PRNext adds Node CommonJS globals to its bundled ESM entry and includes the adjacent HarfBuzz WASM needed by that entry. Upstream bundled notices are preserved in index.node.mjs.\n');
-  const satori = createRequire(path.join(directory, 'index.node.js')).resolve('satori');
-  await cp(createRequire(satori).resolve('harfbuzzjs/hb.wasm'), path.join(target, 'hb.wasm'));
+  await cp(fileURLToPath(new URL('../runtime/og/', import.meta.url)), target, { recursive: true });
 }

package/build/output-contract.mjs

@@ -0,0 +1,41 @@
+import { open, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const OUTPUT_CONTRACT = 'build-output.json';
+const fields = ['version', 'adapter', 'buildId', 'manifest', 'assets', 'server', 'fallback'];
+
+/** The public adapter contract is separate from internal rendering metadata. */
+export function validateBuildOutput(value) {
+  const invalid = reason => { throw new Error(`Invalid PRNext build output: ${reason}`); };
+  if (!value || typeof value !== 'object' || Array.isArray(value)) invalid('expected an object');
+  if (value.version !== 1) invalid(`unsupported version ${value.version}; expected 1`);
+  if (Object.keys(value).some(key => !fields.includes(key)) || fields.some(key => !(key in value))) invalid('unexpected or missing fields');
+  if (!['react', 'static'].includes(value.adapter)) invalid('unsupported adapter');
+  if (typeof value.buildId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value.buildId)) invalid('invalid buildId');
+  if (value.manifest !== 'manifest.json') invalid('manifest must be manifest.json');
+  if (value.adapter === 'static') {
+    if (value.assets !== 'static' || value.server !== null || ![null, 'index.html'].includes(value.fallback)) invalid('invalid static entrypoints');
+  } else if (value.assets !== 'assets' || value.fallback !== null || !value.server ||
+    Object.keys(value.server).sort().join(',') !== 'entry,runtimeContract' ||
+    value.server.entry !== 'runtime/worker.mjs' || value.server.runtimeContract !== 'runtime-contract.json') invalid('invalid React entrypoints');
+  return value;
+}
+
+export async function writeBuildOutput(directory, manifest, { adapter = 'react', spa = false } = {}) {
+  const value = validateBuildOutput({ version: 1, adapter, buildId: manifest.buildId,
+    manifest: 'manifest.json', assets: adapter === 'static' ? 'static' : 'assets',
+    server: adapter === 'static' ? null : { entry: 'runtime/worker.mjs', runtimeContract: 'runtime-contract.json' },
+    fallback: spa ? 'index.html' : null });
+  await writeFile(path.join(directory, OUTPUT_CONTRACT), JSON.stringify(value, null, 2) + '\n');
+  return value;
+}
+
+export async function readBuildOutput(directory) {
+  const file = await open(path.join(directory, OUTPUT_CONTRACT), 'r');
+  try {
+    const bytes = Buffer.alloc(65537);
+    const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > 65536) throw new Error('Invalid PRNext build output: exceeds 64 KiB');
+    return validateBuildOutput(JSON.parse(bytes.subarray(0, bytesRead).toString('utf8')));
+  } finally { await file.close(); }
+}

package/build/precompress.mjs

@@ -49,6 +49,19 @@ async function compress(filename, cacheDirectory) {
   const original = await stat(filename);
   if (!original.size) return 'skipped';
   const sidecar = filename + '.gz';
+  // Static builders may already supply gzip files. Validate them rather than
+  // overwriting public input or publishing a mismatched encoded response.
+  const existing = await stat(sidecar).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  if (existing) {
+    const input = createReadStream(sidecar), unzip = createGunzip();
+    const verified = digest(unzip, original.size);
+    const pumping = pipeline(input, unzip);
+    const [actual, expected] = await Promise.all([verified, digest(createReadStream(filename)), pumping]);
+    if (actual !== expected) throw new Error(`Precompressed asset does not match its source: ${path.basename(sidecar)}`);
+    await utimes(filename, original.atimeMs / 1000, original.mtimeMs / 1000);
+    await utimes(sidecar, original.atimeMs / 1000, original.mtimeMs / 1000);
+    return 'reused';
+  }
   const key = cacheDirectory && original.size <= 64*1024*1024 ? await digest(createReadStream(filename)) : null;
   const cached = key && path.join(cacheDirectory,key+'.gz');
   let reused = false;

package/build/scan.mjs

@@ -61,7 +61,7 @@ export async function scanProject(projectRoot, { basePath = '', pageExtensions,
   const appRoots = [];
   for (const name of ['app', 'src/app']) if (await exists(path.join(root, name))) appRoots.push(path.join(root, name));
   if (appRoots.length > 1) throw new Error('Both app/ and src/app/ exist. Keep exactly one App Router directory.');
-  if (!roots.length && !appRoots.length) throw new Error('No pages/, src/pages/, app/, or src/app/ directory found. Create app/page.tsx or pages/index.tsx to start.');
+  if (!roots.length && !appRoots.length) throw new Error('The React adapter needs a pages/, src/pages/, app/, or src/app/ directory. Create app/page.tsx or pages/index.tsx to start. For a Vite or other static site, run its own build, then prnext build --adapter static --from dist.');
   const pageRoot = roots[0];
   const files = (pageRoot ? await walk(pageRoot) : []).filter(file => sourceExtension.test(file) && !file.endsWith('.d.ts'));
   const routes = [];