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

package/README.md

@@ -1,43 +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.12-alpha — stability and bounded resource usage.** 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 are part of the release path. Rebuild dynamic applications with `prnext build` after upgrading, then restart them.
-
-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
@@ -61,6 +39,44 @@ Install only `@thomas.f/prnext`. Keep optional dependencies enabled: npm install
 
 `reactCompiler: false` and `typedRoutes: false` are supported. Enabling either option fails with an explicit diagnostic: PRNext does not yet run React Compiler or generate and validate typed route declarations. Keep builds that require these features on Next.js.
 
+The current source candidate also supports `devIndicators: false`, configured
+`experimental.optimizePackageImports` for pure ESM barrels with `sideEffects: false`,
+and App Router `maxDuration` values from 1 to 300 seconds. Import optimization
+preserves client/server boundaries and falls back to normal bundling when a barrel
+cannot be safely expanded. Duplicate App convention files follow `pageExtensions`
+priority and emit a warning. Identical public/App metadata files are accepted;
+conflicting content still fails explicitly. Route Handlers can call shared
+`use server` functions directly; pages retain their Flight/Server Action
+registrations. Mixed npm component exports preserve the real React server
+instance without requiring unused client hooks to exist in that environment.
+
+Node Route Handlers and Server Actions can use `after()` from `next/server`. Callbacks run after the
+response finishes or disconnects, including error responses, and retain their
+request context. Tracked work prevents idle worker retirement without blocking the
+next HTTP request. There are at most 128 tasks per request, within `maxDuration`
+(25 seconds by default, including the response's running time). Cookie reads are supported;
+post-response cookie writes are rejected. Server Actions wait for the HTTP response
+to finish, not just their intermediate Flight render. Server Component and Edge
+`after()` lifecycles are not implemented and fail explicitly. `revalidateTag`,
+`revalidatePath` and `updateTag` are also rejected inside an `after()` callback;
+perform supported invalidation in the Route Handler or Server Action before
+returning. This differs from the full Next.js lifecycle. During service shutdown,
+the 30-second standalone drain (35 seconds for global Host shutdown) can shorten a route's larger `maxDuration`. Ordinary sleep/eviction instead allows a 300-second drain. Forced
+termination, a memory-budget violation or a machine failure can still interrupt
+work; use durable external job storage for tasks that must survive these events.
+
+`experimental.proxyClientMaxBodySize` accepts a byte count or a size such as
+`'25mb'`, up to 32 MiB (default 10 MiB). Like Next's body clone, overflow retains
+only complete chunks before the limit and warns; a chunk crossing the limit is
+discarded. General request ingress remains capped at 32 MiB and Server Actions at
+8 MiB. PostgreSQL's `pg` stays external by default so its optional native driver
+remains lazy; explicitly putting `pg` in `transpilePackages` opts out.
+
+Google font build inputs are cached under `.prnext-cache/fonts-v1` (64 MiB,
+256 entries, verified content hashes). A warm cache permits offline rebuilding;
+a cold build still needs access to Google's font endpoints. Remove this cache to
+refresh downloaded font inputs. This does not cache dynamic page responses.
+
 Set `typescript: {}` to check an existing `tsconfig.json` during production builds using the application's installed `typescript` package. `typescript.tsconfigPath` selects a custom configuration for type checking and compilation, including its inherited path aliases. `typescript.ignoreBuildErrors: true` explicitly skips the production check; development builds also skip it. Checks run in a temporary child process without emitting files or editing the configuration. Unlike Next.js, omitting `typescript` preserves PRNext's existing transpile-only behavior. PRNext does not install TypeScript, create `next-env.d.ts`, generate Next.js route types, or implement the Next.js TypeScript language-service plugin; retain the project's type declarations and run separate editor checks as needed. See the [Next.js option definitions](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript).
 
 </details>
@@ -68,7 +84,7 @@ Set `typescript: {}` to check an existing `tsconfig.json` during production buil
 <details>
 <summary><strong>Upgrade · update an existing PRNext project</strong></summary>
 
-Stop your development or production process before changing dependencies. If you use `pstart`, follow the [persistent app upgrade guide](https://github.com/Lorkydey/PRNext#upgrade-persistent-apps) first.
+Stop your development or production process before changing dependencies. If you use `pstart`, follow the [persistent app upgrade guide](#upgrade-persistent-apps) first.
 
 ```sh
 npm install @thomas.f/prnext@alpha react@19.3.0 react-dom@19.3.0 react-server-dom-webpack@19.3.0
@@ -223,9 +239,18 @@ Client disconnections release response permits and close incomplete transport la
 
 Explicit disposal of a worker pool starts a separate graceful shutdown: tracked work has up to 30 seconds to drain before Rust terminates and reaps the process, including a blocked JavaScript event loop. This shutdown grace does not limit normal idle cache finalization. Arbitrary detached tasks are outside the tracked lifecycle; applications that rely on them or long-lived in-process state should use `speed` or `classic` to keep their primary host warm. Such tasks are still not preserved across shutdown or worker failure.
 
-The `memory` profile allows 28 live responses with 8 render starts, a 1 MiB response buffer budget and its existing small V8 nursery. `balanced` retains 32 live responses and `speed` retains 128. These limits bound concurrency independently of idle retirement.
+Each profile keeps its own admission, buffering and idle policy. Limits below are per worker host; render starts and live responses are separate budgets.
+
+| Profile | Render starts | Live responses | API concurrency | Response buffer | Primary idle deadline |
+|---|---:|---:|---:|---:|---|
+| `balanced` | 16 | 32 | 256 | 4 MiB | 300 seconds |
+| `speed` | 32 | 128 | 512 | 16 MiB | Keep warm |
+| `memory` | 8 | 28 | 64 | 1 MiB | 30 seconds |
+| `classic` | 16 | 32 | 512 | 8 MiB | Keep warm |
 
-`balanced` uses a 4 MiB V8 semi-space without `--optimize-for-size`, keeping its RSC young-generation setting at 16 MiB. This selection reduces measured CPU per response at the cost of higher RSS than the previous size policy. It keeps 16 render starts, a 4 MiB response buffer and 300-second host retirement; `speed` uses 32 starts, a 16 MiB buffer and keeps hosts warm. In the measured SSR/streaming fixtures, cumulative RSS remained below Next.js, but that is not a universal memory guarantee. The final Windows validation includes three 30-second measurements per scenario after warm-up and a one-hour mixed endurance run. The CPU/RSS trade-off remains workload-dependent; comparable Linux performance and Nginx benchmarks have not been run.
+On Linux with Node's `process.execve` available (Node 22.15+/23.11+), production `prnext start` replaces its CLI process with the native server. This removes a resident Node launcher from every profile without shrinking render or response budgets. Rust handles SIGINT, SIGTERM and SIGHUP gracefully; Linux also kills Node workers if their native parent dies, including when JavaScript is blocked. Explicit `--shutdown-on-stdin-eof` remains supported. Windows, macOS, older Node versions, IPC callers and Node instrumentation keep the supervised launch path. Only heap-sizing Node flags are eligible for replacement; other flags and `NODE_V8_COVERAGE` conservatively retain supervision. Node still labels `process.execve` experimental. This change does not remove the supervisors used by `pstart`, or change `host` and development mode.
+
+`balanced` keeps its 4 MiB V8 semi-space without `--optimize-for-size`. `speed` keeps its 16 MiB semi-space, larger concurrency and buffers, and warm hosts. `memory` keeps V8's size policy and early retirement; `classic` preserves its original V8 settings. Node heap flags can take precedence over the RSC isolate's young-generation resource limit: these settings are not total RSS caps. The earlier Windows V6 validation includes three 30-second measurements per scenario and a one-hour mixed endurance run; it predates this launcher change and is not an endurance result for this candidate. Workload and platform affect the CPU/RSS trade-off; a comparable Linux Nginx benchmark remains pending.
 
 An explicit `NODE_OPTIONS="--max-semi-space-size=4"` (including Node's underscore spelling) overrides the profile's nursery policy. PRNext also omits `--optimize-for-size` in that case: on Node 24.19.0, V8 otherwise replaces the explicit value with 1 MiB. This opts out of V8's broader size policy as well, so CPU and memory consumption can change; measure the chosen value for your workload. It does not add an old-generation heap limit or change the profile's admission, response buffers or idle retirement. Without an explicit override, PRNext uses the defaults of the selected profile.
 
@@ -247,74 +272,289 @@ improved small-file throughput by about 5% in two short configuration trials,
 but allows four times as many submitted helper tasks. It has not received the
 same endurance validation and is not a universal profile improvement.
 
-Results depend on your workload; see the [benchmark and its methodology](https://github.com/Lorkydey/PRNext#early-benchmarks-against-nextjs).
+Results depend on your workload; see the [benchmark and its methodology](#early-benchmarks-against-nextjs).
+
+</details>
+
+## Early benchmarks against Next.js
+
+Dynamic streaming with 128 concurrent clients and a deterministic local backend delayed by 40 ms:
+
+| Configuration | RAM | CPU load¹ | CPU/response | Throughput |
+|---|---:|---:|---:|---:|
+| Next.js | 605 MiB | 164% | 2.442 ms | 673 req/s |
+| **Balanced** | **207 MiB** | 124% | 1.704 ms | 726 req/s |
+| **Speed** | 496 MiB | 250% | **0.926 ms** | **2,698 req/s** |
+| **Memory** | **179 MiB** | **75%** | 2.067 ms | 362 req/s |
+| **Classic** | 303 MiB | 90% | 1.241 ms | 723 req/s |
+
+<details>
+<summary><strong>Benchmark methodology & trade-offs</strong></summary>
+
+¹ 100% CPU = one fully utilized CPU core. RAM is measured under load.
+
+Measured September 27, 2026, on Apple M4 against Next.js 15.5.12. Values are medians of three six-second runs using identical application sources. This table covers one streaming scenario, not an overall average or guaranteed gains. Functional parity was checked before benchmarking.
+
+Under concurrent streaming, `memory` used 179 MiB versus 207 MiB for `balanced`, but served 362 versus 726 responses/s. On concurrent SSR, it used slightly more memory than `balanced`. The lowest-memory profile is workload-dependent.
 
 </details>
 
 ## 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>Migration audit, inspector and multi-app hosting</strong></summary>
+<summary><strong>Deploy to PRNext Cloud (local development)</strong></summary>
+
+### Deploy to PRNext Cloud
 
-### Migration audit, inspector and multi-app hosting
+The local CLI now supports browser login and source deployments. This feature is
+not yet included in a published npm release or deployed to the public Cloud app.
 
 ```sh
+prn login
+prn deploy ./my-app
+prn update ./my-app
+prn whoami
+prn logout
+```
+
+`prnext` accepts the same commands. Login opens the browser and reuses its session,
+or returns to terminal approval after web sign-in. Confirm the code shown in your
+terminal. `--no-browser` prints the URL for manual authorization.
+
+`deploy` creates an upload project and saves its link in the ignored
+`.prnext-cloud/project.json`; `update` sends changes to that same project.
+`deploy --project ID` links an existing upload project. `--dry-run` lists source
+files without connecting or uploading; `--no-wait` returns after queueing.
+`--timeout SECONDS` controls waiting (default 600). After interruption or
+`--no-wait`, `update` resumes the recorded request first; run it again to deploy
+further changes. Server-side request IDs prevent duplicate queued builds.
+
+Archives exclude `.env*`, credentials, `node_modules`, `.git`, generated
+`.next`/`.prnext*` output and `.local`. Root `.gitignore` and `.prnextignore`
+support additional glob exclusions and `!` rules; nested/global Git ignore files
+are not read. Mandatory exclusions cannot be re-included. Nonexcluded symbolic
+links are refused. On a compatible Host server: 100 MiB ZIP, 500 MiB expanded,
+15,000 files and 64 MiB per file. Transfers use resumable 4 MiB chunks on the VPS;
+legacy servers retain their 7 MiB upload limit. No object storage is required.
+
+When production `.env` files are detected, `deploy` and `update` ask before
+importing variables (default: no). `--with-env` explicitly opts in;
+`--without-env` skips the prompt. Noninteractive commands skip import unless
+`--with-env` is set. Variables travel through the encrypted environment API,
+never inside the source ZIP or project link. Matching remote keys are replaced;
+other keys remain. `NEXT_PUBLIC_` values may be exposed in the browser bundle.
+This feature requires the updated Host API and remains unpublished.
+Use project environment settings for secrets; inspect `--dry-run` for other
+sensitive files in your own source tree.
+
+Credentials stay under `~/.prnext/cloud/` (or private `PRNEXT_CLOUD_HOME`, outside
+the source directory). Tokens are scoped to project reads/uploads/deployments,
+expire after 30 days, and can be revoked with `logout` or in workspace settings.
+Browser sign-out does not revoke authorized terminals.
+
+For a local Cloud server, use `--server http://127.0.0.1:3003` or
+`PRNEXT_CLOUD_URL`. From this checkout, run
+`node packages/prnext/cli.mjs login --server http://127.0.0.1:3003`.
+Production defaults to `https://app.prnext.dev`; credentials are isolated by origin.
+
+A configured isolated Linux worker is required to deploy. A local Windows panel
+supports login and dry runs, but reports unavailable hosting explicitly.
+Approved offline dependencies, runtime network isolation and current Cloud quotas
+still apply; these commands do not bypass the hosting worker or configure DNS/TLS.
+
+</details>
+
+
+<details>
+<summary><strong>Check a migration before switching</strong></summary>
+
+### Check a migration before switching
+
+```sh
+prnext migrate ./my-app --check
 prnext migrate ./my-app --check --json
 prnext migrate ./my-app --check --against http://localhost:3000 --candidate http://localhost:3001 --routes paths.json
+```
+
+The source audit reports unsupported Next imports with file and line numbers, client/server import conflicts, dependency versions and scripts requiring manual changes. It leaves sources, package files and builds untouched. Configuration files are evaluated by the existing preflight; installed dependencies and custom loaders still require a build. Warnings are distinct from blocking errors. A failed audit or response comparison exits with code 1.
+
+For comparison, start the existing Next application and the PRNext candidate separately. `paths.json` is a JSON array such as `["/", "/products/123", "/api/catalog"]`; without it, the command selects non-parameterized page routes from the audit. It sends GET requests without authentication, follows no redirects, and compares status, content type, redirect destinations and bodies. JSON object key order is ignored; HTML compares text with scripts/styles removed. This verifies response samples, not hydration, styling, interactive behavior or every dynamic path. Timing observations are not controlled performance benchmarks. `--timeout 10000` sets each response's deadline in milliseconds.
+
+</details>
+
+<details>
+<summary><strong>Inspect routes, cache and timings</strong></summary>
+
+### Inspect routes, cache and timings
+
+```sh
+prnext build ./my-app
 prnext start ./my-app --inspect
+# In another terminal, after visiting the application:
+prnext inspect ./my-app
 prnext inspect ./my-app --json
-prnext host prnext.host.json --check
-prnext host prnext.host.json
-prnext host prnext.host.json --status --json
+prnext inspect ./my-app --otlp > metrics.json
 ```
 
-The migration audit reports file/line diagnostics without rewriting the application. Response comparison checks GET status, redirects and normalized bodies between servers you start separately. HTML comparison excludes scripts/styles and does not replace browser tests.
+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.
 
-The inspector explains build decisions and summarizes optional local HTTP, fetch, cache and invalidation samples. Durations end at response headers. Runtime logs omit request bodies, credentials and query strings, and hash tag/path identifiers. Measurements are bounded and may drop samples under load.
+`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.
 
-The host uses separate native server/Node process trees, starts apps on demand and stops idle apps. A minimal configuration is `{"memoryMb":512,"apps":[{"name":"site","root":"./site","hosts":["site.localhost"],"memoryMb":256,"idleSeconds":300}]}`. Roots are relative to this file; apps must already have production builds. Additional app options are `workers`, `profile`, `env` and `inspect`. The listener defaults to `127.0.0.1:8080`; set `hostname` and `port` explicitly when needed.
+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.
 
-Memory budgets reserve capacity and monitor process-tree RSS about once per second. An excess stops the app and imposes a 30-second cooldown; this is not a kernel hard limit. Leave memory for the gateway, OS and overshoot. Sleeping loses in-process state and background work. Apps run as the same OS user, so this mode is for trusted applications. HTTP streaming is supported; WebSocket upgrades are not. Configure public DNS/TLS and OS services separately.
+</details>
 
-The Windows release check used four apps on one shared CPU and a 1 GiB Job commit budget. Two 30-second mixed SSR/stream/API trials measured about 333 requests/s through `host` versus 361 directly with the same V8 heap guard. Matching direct controls followed the host trials; this roughly 8% cost is specific to the fixture. Three sleep/resume cycles per trial used `idleSeconds: 3`: 32 simultaneous arrivals completed in 1.92–2.35 seconds, with one startup per app and no failures. The default whole-app deadline remains 300 seconds. The gateway's status/RSS monitor continues while apps sleep, so idle CPU is not zero. No host endurance or Linux performance result is claimed.
+<details>
+<summary><strong>Host several applications</strong></summary>
 
-See the [repository guide and example configuration](https://github.com/Lorkydey/PRNext#host-several-applications) for the full workflow.
+### Host several applications
+
+```sh
+npm run build -- examples/basic
+npm run build -- examples/app
+node packages/prnext/cli.mjs host examples/hosting/prnext.host.json --check
+node packages/prnext/cli.mjs host examples/hosting/prnext.host.json
+# In another terminal:
+node packages/prnext/cli.mjs host examples/hosting/prnext.host.json --status
+```
+
+The example routes `basic.localhost:8080` and `app.localhost:8080` to separate applications. Resolve those hostnames to the listener address, or supply their exact `Host` header when testing. Installed packages use `prnext host config.json`. Configuration roots are relative to the JSON file. Each app has a unique name, root and exact hostname list, with optional `memoryMb`, `idleSeconds`, `workers`, `profile`, `env` and `inspect` settings. `--status --json` reads the local status snapshot beside the configuration, including its age; it does not connect to a live admin endpoint. Restart the host to apply configuration or build changes.
+
+The native gateway keeps each application asleep until requested. A waking app reserves its configured memory budget; if capacity is full, inactive apps can release theirs, while busy requests receive 503 rather than starting an unbudgeted app. Requests and streaming responses hold their reservation until completion or cancellation. Idle apps begin stopping after `idleSeconds` and wake on the next request. Sleep and capacity eviction retain the memory reservation while the child drains supported `after()` and ISR work, allowing up to 300 seconds plus five seconds for process cleanup. A wake waiting for that capacity can take longer. Status shows `draining` with the process still present; monitoring and memory-budget enforcement continue. Global Host shutdown shortens outstanding retirement to its own 35-second deadline. Persistent caches remain on disk; in-process state and untracked background jobs do not survive sleep. Apps receive their configured environment and a small platform environment allowlist, then load their own `.env` files.
+
+The watchdog samples the RSS of each app's native server and descendants about once per second. Exceeding `memoryMb` stops that process tree, can interrupt its in-flight requests, and imposes a 30-second cooldown. V8 also receives an initial heap guard unless the app config supplies `NODE_OPTIONS`. These are sampled operating budgets, not kernel-enforced hard limits; allow extra RAM for the gateway, the OS and sampling overshoot. Process separation isolates caches, environment and ordinary failures, but apps run as the same OS user: host only trusted applications. Use separate users or containers for untrusted tenants.
+
+The 0.1.12-alpha Windows host check used four applications sharing one CPU and a 1 GiB Job commit budget. Two 30-second mixed SSR/stream/API trials measured about 333 requests/s through `host` versus 361 directly with the same V8 heap guard (about 8% gateway cost in this fixture). The matching direct controls followed the host trials; these short runs are not a general capacity guarantee. Three sleep/resume cycles per trial used `idleSeconds: 3` to exercise retirement: 32 simultaneous arrivals completed in 1.92–2.35 seconds, with one startup per application and no failures. The default whole-app deadline remains 300 seconds. The gateway keeps its one-second status/RSS monitor running while apps sleep; idle CPU is not zero. No host endurance or Linux performance result is claimed.
+
+Hosting supports HTTP streaming and preserves the original application Host. Protocol upgrades such as WebSockets return 501. Put a TLS reverse proxy in front for public hosting; this command does not configure DNS, TLS, OS services or deploy to a VPS. Windows, macOS and Linux use the same JSON format and CLI.
 
 </details>
 
 <details>
-<summary><strong>Persistent production commands</strong></summary>
+<summary><strong>Keep production apps running</strong></summary>
+
+### Keep production apps running
+
+`prnext start` keeps its normal foreground behavior. Use the separate persistent commands when an app should survive closing the terminal:
+
+```sh
+prnext build ./my-app
+prnext pstart ./my-app --name web --port 3000
+prnext pstatus
+prnext plogs web --follow
+# After rebuilding the app:
+prnext prestart web
+prnext pstop web
+```
+
+`pstart` starts a detached supervisor and returns once the app passes its health check. Applications restart after a crash with increasing delays; ten failures within five minutes stop retries until `prestart`. A separate watchdog restarts the supervisor after a crash or an unresponsive event loop. Each app has a stable HTTP listener and its own native server and workers. This mode adds a Node HTTP proxy and two supervisor processes; it does not enable the idle sleep or memory reservations of `prnext host`.
+
+`prestart` copies the current production build, starts a replacement on a private port, and sends a GET to `--health-path` (default `/`). A 2xx or 3xx response must arrive within `--health-timeout 15000` milliseconds. Only then does new traffic switch to the replacement. If startup or the health check fails, the existing healthy instance keeps serving. Existing HTTP streams can finish for up to `--drain-timeout 30000` milliseconds, after which remaining requests are closed. Choose a health route that checks the dependencies your application needs. Two generations temporarily use memory and disk space during replacement.
+
+Build copies live under the project's ignored `.prnext-persistent` directory and are removed after their processes stop. Rebuilding does not replace the active generation's compiled files. Project dependencies, `public` files and persistent caches remain shared; avoid changing dependencies or deleting public assets while old requests still need them. HTTP streaming, original Host headers and multiple cookies are preserved. WebSocket/protocol upgrades return 501. A supervisor crash can interrupt requests; health-checked replacement is not a guarantee against machine failures or incompatible application changes. A TLS reverse proxy can sit in front of the persistent listener.
+
+Available commands:
+
+| Command | Behavior |
+| --- | --- |
+| `prnext pstart [directory] --name NAME` | Start or restore an app; identical repeated starts are idempotent |
+| `prnext prestart [name] [--all]` | Load the current build through a health-checked replacement |
+| `prnext pstop [name] [--all]` | Stop apps and keep them stopped across supervisor restarts |
+| `prnext pdelete [name] [--all]` | Stop apps and remove their saved configuration; retain logs |
+| `prnext pstatus [name] [--json]` / `prnext plist` | Show status, PIDs, build IDs, starts and active requests |
+| `prnext plogs [name] --lines 100 --follow` | Read/tail app output; `--supervisor` selects supervisor logs |
+| `prnext pdown` | Stop the supervisor and apps, retaining enabled flags for their next launch |
+| `prnext pstartup [--remove]` | Enable/remove automatic restoration at user login |
 
-### Persistent production commands
+Without a name, `prestart`, `pstop`, `pdelete` and `plogs` select the app registered for the current directory. `pstart` accepts `--hostname`, `--port`, `--workers`, `--profile`, `--inspect`, `--health-path`, `--health-timeout` and `--drain-timeout`; see `prnext pstart --help`. Change saved listener/settings with `pdelete`, then `pstart`. Applications load their project `.env` files; arbitrary caller-shell variables and secrets are not copied into the saved registry. The state directory defaults to `~/.prnext/processes`; set `PRNEXT_PM_HOME` consistently for a separate supervisor. Keep that directory private: it contains local control credentials and application logs. Logs rotate at 10 MiB with three retained segments per app and for the supervisor. App output can contain whatever the application logs.
 
-`prnext start` remains a foreground command. Use `prnext pstart --name web --port 3000` to keep a built app running after the terminal closes. `prnext pstatus` (or `plist`) lists apps, `prnext plogs web --follow` tails logs, `prnext prestart web` loads the current build through a health check, and `prnext pstop web` stops it. `pdelete` removes saved settings; `pdown` stops the supervisor while preserving enabled apps for restoration. Lifecycle commands accept `--all` where shown by `prnext pstart --help`.
+`pstartup` is opt-in and enables restoration on the **next user login**. On Windows it registers a hidden scheduled task for the current account; on macOS it writes a user LaunchAgent; on Linux it enables a systemd user service. These definitions restart a failed watchdog once managed by the OS. Windows and macOS user startup do not run before login. A Linux administrator can enable user lingering separately for boot-time operation without an interactive login. No OS startup settings change just by running `pstart`, and the command does not install a Windows system service or alter other accounts. Run `pstartup` again after moving or upgrading Node or the PRNext package. Platform references: [Windows scheduled tasks](https://learn.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtasksettingsset), [Apple launch agents](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html), [systemd user lingering](https://www.freedesktop.org/software/systemd/man/252/loginctl.html).
 
-Apps restart after crashes with increasing delays and a retry limit. A separate watchdog supervises the manager. Replacements get a private build copy and must return HTTP 2xx/3xx from `--health-path /` within `--health-timeout 15000` ms before traffic switches; a failed candidate leaves the old instance serving. Existing requests can finish for `--drain-timeout 30000` ms. Dependencies, public files and disk caches remain shared. This adds a Node HTTP proxy; WebSocket upgrades are not supported and crashes can interrupt requests.
+### Upgrade persistent apps
 
-Settings, control credentials and logs live in `~/.prnext/processes` (`PRNEXT_PM_HOME` overrides it). Logs rotate at 10 MiB plus three older segments. Apps load project `.env` files; caller-shell secrets are not saved. `prnext pstartup` opts into restoration on the next user login through Windows Task Scheduler, a macOS LaunchAgent or a Linux systemd user service; `--remove` removes that startup configuration. Windows/macOS startup is per-user, not a pre-login system service. Linux boot-time operation requires administrator-configured user lingering. Re-run `pstartup` after moving or upgrading Node or PRNext. See the [persistent command guide](https://github.com/Lorkydey/PRNext#keep-production-apps-running).
+The supervisor may be shared by several projects. Use the same user and `PRNEXT_PM_HOME` throughout, and record the applications and their settings first:
 
-Before upgrading a supervised application, follow the [persistent app upgrade guide](https://github.com/Lorkydey/PRNext#upgrade-persistent-apps).
+```sh
+npx --no-install prnext pstatus --json
+```
+
+Before changing package files, stop the apps and supervisor using the **old installation**. These commands affect **all apps managed by that supervisor**, so schedule the interruption accordingly:
+
+```sh
+npx --no-install prnext pstop --all
+npx --no-install prnext pdown
+```
+
+Install the update and rebuild each affected project as described under [Install & upgrade](#install--upgrade). Using the new CLI, restart each app with its original name, port and other options. For example:
+
+```sh
+npx --no-install prnext pstart --name web --port 3000
+```
+
+If the saved Node or native executable path changed, remove that app's saved entry with `prnext pdelete NAME`, then register it again with `prnext pstart` and its recorded options. This removes saved settings but retains logs. If login startup was enabled, re-run `prnext pstartup` to refresh its paths.
+
+`pdown` alone keeps apps enabled for restoration; stop them first to prevent an old configuration from restarting during the upgrade.
 
 </details>
 
 <details>
-<summary><strong>Platforms</strong></summary>
+<summary><strong>Develop from this repository</strong></summary>
+
+### Develop from this repository
+
+Install Node.js 22+ and Rust with rustup, then run:
+
+```sh
+npm ci
+npm run build:native
+npm run dev -- examples/app
+```
 
-### Platforms
+These commands also work in PowerShell and Command Prompt. On Windows, source builds require Visual Studio Build Tools with the Desktop development with C++ workload and a Windows SDK, plus NASM on x64. Rustup selects the repository's Rust 1.98 toolchain. Linux source builds need a C/C++ toolchain, NASM and pkg-config; macOS needs Xcode command line tools and NASM.
 
-Native package targets cover Windows MSVC arm64/x64, macOS arm64/x64 and Linux glibc arm64/x64. Windows runs directly from PowerShell or Command Prompt, without WSL. Alpine/musl is not a prebuilt target. The native Linux CI builds use Ubuntu 22.04 with glibc 2.35. Framework and native components use matching release versions.
+For production locally, run `npm run build -- examples/app`, then `npm run start -- examples/app`. Standalone output runs with `node server.js` on its build OS and architecture, including Windows. Published native packages remove the Rust/C++ build requirement for consumers. Keep the framework and platform components on matching release versions.
 
-Keep npm optional dependencies enabled: PRNext automatically installs the binary for your platform. Rust is not required to use the published package.
+For source builds, `cargo build --release --locked --features gzip-zlib-rs` enables an experimental alternative gzip/deflate backend. Ubuntu x64 trials reduced JSON API CPU cost but increased cumulative streaming RSS, so this option is disabled by default. It also changes the Rust PNG/TIFF codecs; runtime profiles and Node heap settings remain unchanged. Compare CPU, response size and memory on your workload before choosing it.
 
 </details>
 
-## Links and feedback
+## Contributing
 
-- Website and benchmarks: [prnext.dev](https://prnext.dev)
-- Source and contributions: [Lorkydey/PRNext](https://github.com/Lorkydey/PRNext)
-- Project updates on X: [@PRNextdev](https://x.com/PRNextdev)
-- Bug reports: [GitHub Issues](https://github.com/Lorkydey/PRNext/issues)
-- Questions and suggestions: [contact@heythomas.dev](mailto:contact@heythomas.dev)
+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/actions.mjs

@@ -205,6 +205,10 @@ export function createServerActions({ projectRoot }) {
     transform(source,file,mode) {
       if(!source.includes('use server')) return source;
       const result=analyze(source,file);
+      // A Route Handler invokes the implementation as ordinary server code.
+      // It does not serialize functions through Flight or manufacture proxies.
+      // Analyze first to preserve validation and the shared action registry.
+      if(mode==='route') return source;
       if(mode==='rsc') return result.server;
       if(result.moduleServer) return `import {createServerReference} from 'prnext-internal:action-${mode==='browser'?'client':'ssr'}';\n`+result.declared.map((item,index)=>`const action${index}=createServerReference(${JSON.stringify(item.id)});export {action${index} as ${JSON.stringify(item.name)}};`).join('\n');
       if(result.inline) throw new Error(`Inline Server Actions cannot be imported into the client graph (${file}); move the action to a module marked 'use server'.`);

package/build/app-config.mjs

@@ -79,6 +79,7 @@ export async function validateAppConfig(file) {
       config.generateStaticParams = true;
       continue;
     }
+    if (item.name === 'maxDuration' && Number.isSafeInteger(value) && value >= 1 && value <= 300) { config.maxDuration = value; continue; }
     if (allowed.includes(value) || (item.name === 'revalidate' && Number.isSafeInteger(value) && value >= 0)) { config[item.name] = value; continue; }
     throw new Error(`App Router export ${item.name} in ${file} is not supported with this value.${allowed.length ? ` Supported literal values: ${allowed.map(value => JSON.stringify(value)).join(', ')}${item.name === 'revalidate' ? ', or a nonnegative integer' : ''}.` : ''}`);
   }
@@ -105,6 +106,7 @@ export function mergeAppConfig(configs) {
   }
   let forceDynamic = false;
   for (const config of configs) {
+    if (config.maxDuration !== undefined) merged.maxDuration = config.maxDuration;
     if (config.runtime === 'edge') merged.runtime = 'edge';
     else if (config.runtime === 'nodejs') delete merged.runtime;
     // The first explicit ancestor decides whether a blocking route is allowed.