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

package/README.md

@@ -10,7 +10,15 @@ A Rust-powered runtime for Next.js projects, with React and npm modules running
 
 ## 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.
+**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.
 
@@ -61,6 +69,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 +114,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 +269,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.
 
-`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.
+| 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 |
+
+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 +302,248 @@ 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
 
 <details>
-<summary><strong>Migration audit, inspector and multi-app hosting</strong></summary>
+<summary><strong>Deploy to PRNext Cloud (local development)</strong></summary>
 
-### Migration audit, inspector and multi-app hosting
+### Deploy to PRNext Cloud
+
+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
 ```
 
-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.
+
+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>
+
+<details>
+<summary><strong>Host several applications</strong></summary>
+
+### 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 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.
+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 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.
+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.
 
-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.
+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 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.
+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.
 
-See the [repository guide and example configuration](https://github.com/Lorkydey/PRNext#host-several-applications) for the full workflow.
+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:
 
-### Persistent production 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 |
 
-`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`.
+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.
 
-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.
+`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).
 
-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).
+### Upgrade persistent apps
 
-Before upgrading a supervised application, follow the [persistent app upgrade guide](https://github.com/Lorkydey/PRNext#upgrade-persistent-apps).
+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:
+
+```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>
 
-### Platforms
+### Develop from this repository
 
-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.
+Install Node.js 22+ and Rust with rustup, then run:
 
-Keep npm optional dependencies enabled: PRNext automatically installs the binary for your platform. Rust is not required to use the published package.
+```sh
+npm ci
+npm run build:native
+npm run dev -- examples/app
+```
 
-</details>
+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.
 
-## Links and feedback
+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.
 
-- 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)
+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>
 
 <details>
 <summary><strong>License & credits</strong></summary>

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.

package/build/app.mjs

@@ -118,7 +118,7 @@ function boundaryEntry(boundary) {
   return `import * as client from ${JSON.stringify(boundary.file)};\n` + boundary.exports.map((name, index) => `const ref${index}=client[${JSON.stringify(name)}];export {ref${index} as ${JSON.stringify(name)}};`).join('\n');
 }
 
-function routeEntry(route, globalError) {
+function routeEntry(route, globalError, dev) {
   if (route.kind === 'api') return `export * from ${JSON.stringify(route.file)};`;
   const imports = [`import * as page from ${JSON.stringify(route.file)};`, 'export {page};', `export const pageConfig=${JSON.stringify(route.pageConfig || {})};`];
   const rootLayout = route.segments.find(segment => segment.layout)?.layout;
@@ -144,6 +144,9 @@ function routeEntry(route, globalError) {
   if (route.routing || route.segments.some(segment => segment.error)) imports.push(`export {default as ErrorBoundary} from ${JSON.stringify(path.join(packageRoot, 'compat/app-error-boundary.cjs'))};`);
   if (route.routing) {
     let index = 0;
+    // Only scaffold objects owned by this compiler are immutable. Imported
+    // modules and config values retain their original live bindings/behavior.
+    const structural = source => dev ? source : `Object.freeze(${source})`;
     function serialize(value) {
       const files = [];
       for (const [name, file] of Object.entries(value.files)) {
@@ -151,7 +154,7 @@ function routeEntry(route, globalError) {
         imports.push(`import * as ${binding} from ${JSON.stringify(file)};`);
         files.push(`${JSON.stringify(name)}:${binding}`);
       }
-      return `{path:${JSON.stringify(value.path)},segment:${JSON.stringify(value.segment)},pattern:${JSON.stringify(value.pattern)},layoutId:${JSON.stringify(value.layoutId)},config:${JSON.stringify(value.config || {})},interception:${JSON.stringify(value.interception || null)},files:{${files.join(',')}},children:[${value.children.map(serialize).join(',')}],slots:{${Object.entries(value.slots).map(([name, child]) => `${JSON.stringify(name)}:${serialize(child)}`).join(',')}}}`;
+      return structural(`{path:${JSON.stringify(value.path)},segment:${JSON.stringify(value.segment)},pattern:${JSON.stringify(value.pattern)},layoutId:${JSON.stringify(value.layoutId)},config:${JSON.stringify(value.config || {})},interception:${JSON.stringify(value.interception || null)},files:${structural(`{${files.join(',')}}`)},children:${structural(`[${value.children.map(serialize).join(',')}]`)},slots:${structural(`{${Object.entries(value.slots).map(([name, child]) => `${JSON.stringify(name)}:${serialize(child)}`).join(',')}}`)}}`);
     }
     const routing = serialize(route.routing);
     imports.push(`export const routing=${routing};export const interceptionOnly=${!!route.interceptionOnly};`);
@@ -263,8 +266,17 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
           return { path: args.path, namespace: 'prnext-app-empty' };
         });
         esbuild.onLoad({ filter: /.*/, namespace: 'prnext-app-empty' }, () => ({ contents: '', loader: 'js' }));
+        if (rsc) esbuild.onLoad({ filter: /^react$/, namespace: 'prnext-rsc-react' }, () => ({
+          // Keep the real singleton while preserving bundler-style CJS access.
+          // Mixed npm modules may export both server-safe components and unused
+          // hook-based components. Native ESM named imports would reject the
+          // entire module because React's server build has no client hooks.
+          contents: `import React from 'react';export default React;export const {${Object.keys(resolveFromProject('react')).filter(name => t.isValidIdentifier(name) && name !== 'default').join(',')}}=React;`,
+          loader: 'js',
+        }));
         esbuild.onResolve({ filter: /^(?:react|react-dom|react-server-dom-webpack)(?:\/|$)/ }, args => {
           if (args.pluginData?.prnextExportScan) return;
+          if (rsc && args.path === 'react' && args.namespace !== 'prnext-rsc-react') return { path: 'react', namespace: 'prnext-rsc-react' };
           return browser ? { path: resolveFromProject.resolve(args.path) } : { path: args.path, external: true };
         });
         if (!browser) {
@@ -446,14 +458,14 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
   }
 
   await mkdir(path.join(stage, 'assets'), { recursive: true });
-  const entries = {};
+  const entries = {}, handlerEntries = {};
   for (const route of routes) {
     const entry = path.join(stage, '.entries', route.id + '.server.mjs');
     if ((route.handlerConfig?.runtime === 'edge' || route.cacheConfig?.runtime === 'edge') && manifest.config?.cacheComponents) throw new Error(`Cache Components cannot run in the Edge Runtime (${route.file}).`);
-    await writeFile(entry, routeEntry(route, globalError));
+    await writeFile(entry, routeEntry(route, globalError, dev));
     if (route.cacheConfig?.runtime === 'edge' && route.kind === 'page') await edgeAppBuild(entry, path.join(stage, 'server', route.id + '.mjs'), 'rsc');
     else if (route.handlerConfig?.runtime === 'edge') await compileEdge({ file: route.file, outfile: path.join(stage, 'server', route.id + '.mjs'), projectRoot: project.root, dev, defineEnvironment });
-    else entries[route.id] = entry;
+    else (route.kind === 'api' ? handlerEntries : entries)[route.id] = entry;
     const instantConfigs = [route.pageConfig, ...(route.segments || []).map(segment=>segment.staticConfig)];
     const collectInstant = node => {if(!node)return;instantConfigs.push(...Object.values(node.config || {}));for(const child of [...(node.children || []),...Object.values(node.slots || {})])collectInstant(child);};
     collectInstant(route.routing);
@@ -466,6 +478,9 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
   }
   manifest.app = { clientModules: {}, actions: {}, actionKey: actions.actionKey };
   const actionRevision = () => [...actions.actions.values()].map(action=>action.id+':'+[...(action.runtimes || [])].sort().join(',')).join(';');
+  // Route Handlers have a Node React environment and must not share RSC chunks
+  // that import registerServerReference or client-reference registration.
+  await serverBuild(handlerEntries, 'server', 'route');
   for (;;) {
     const revision = `${actionRevision()}:${boundaries.size}:${cssFiles.size}:${globalErrorCssFiles.size}`;
     for (const action of actions.actions.values()) {

package/build/bundle-runtime.mjs

@@ -0,0 +1,82 @@
+import { build } from 'esbuild';
+import { lstat, realpath, readdir, writeFile, unlink } from 'node:fs/promises';
+import path from 'node:path';
+
+// Paths used by the native worker, generated application modules, prerender,
+// standalone tracing, compatibility modules and the runtime lifecycle contract.
+// Other relative imports are resolved into shared chunks by this single build.
+export const runtimeEntryNames = Object.freeze([
+  'worker', 'rsc-worker', 'app-render', 'app-stream-html', 'transport', 'request-work',
+  'http', 'app-static', 'route-static', 'render', 'api', 'middleware', 'incremental-cache', 'app-instant',
+  'action-crypto', 'action-client', 'action-ssr', 'edge', 'metadata-route', 'og-loader',
+].sort());
+
+/** Run once, after compiling application/Edge graphs and before any prerender. */
+export async function bundleRuntime(stage) {
+  const resolvedStage = path.resolve(stage);
+  if (!path.basename(resolvedStage).startsWith('.prnext-build-')) {
+    throw new Error('Runtime bundling requires an unpublished PRNext build stage.');
+  }
+  const runtime = path.join(resolvedStage, 'runtime');
+  const [stageInfo, runtimeInfo] = await Promise.all([lstat(resolvedStage), lstat(runtime)]);
+  if (!stageInfo.isDirectory() || stageInfo.isSymbolicLink() || !runtimeInfo.isDirectory() || runtimeInfo.isSymbolicLink()) {
+    throw new Error('Runtime bundling requires ordinary stage and runtime directories.');
+  }
+  const [canonicalStage, canonicalRuntime] = await Promise.all([realpath(resolvedStage), realpath(runtime)]);
+  if (path.relative(canonicalStage, canonicalRuntime) !== 'runtime') {
+    throw new Error('Runtime bundling escaped the build stage.');
+  }
+  const entries = await readdir(runtime, { withFileTypes: true });
+  const originals = entries.filter(entry => entry.name.endsWith('.mjs'));
+  if (originals.some(entry => !entry.isFile() || entry.isSymbolicLink())) {
+    throw new Error('Runtime source modules must be ordinary files.');
+  }
+  for (const name of runtimeEntryNames) {
+    if (!originals.some(entry => entry.name === `${name}.mjs`)) throw new Error(`Missing runtime entry ${name}.mjs`);
+  }
+  // write:false makes compilation atomic with respect to the source runtime:
+  // no files change if parsing or resolution fails. The virtual output is a
+  // sibling so all relative paths have the same depth as the final runtime.
+  const virtualOutput = path.join(resolvedStage, '.runtime-bundle');
+  const result = await build({
+    absWorkingDir: runtime,
+    entryPoints: runtimeEntryNames.map(name => path.join(runtime, `${name}.mjs`)),
+    outdir: virtualOutput,
+    outbase: runtime,
+    entryNames: '[name]',
+    chunkNames: '_shared-[hash]',
+    outExtension: { '.js': '.mjs' },
+    bundle: true,
+    splitting: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node22',
+    packages: 'external',
+    // Edge's prepared VM is already a self-contained CJS artifact. Keeping it
+    // external preserves its delayed import and original execution boundary.
+    external: ['../compat/*', './profiles.json', './*.cjs'],
+    minify: false,
+    sourcemap: false,
+    metafile: true,
+    write: false,
+    logLevel: 'silent',
+  });
+  const emitted = new Map();
+  for (const file of result.outputFiles) {
+    if (path.dirname(file.path) !== virtualOutput || !file.path.endsWith('.mjs')) {
+      throw new Error('Runtime bundler emitted a file outside its flat output directory.');
+    }
+    emitted.set(path.basename(file.path), file.contents);
+  }
+  if (runtimeEntryNames.some(name => !emitted.has(`${name}.mjs`))) throw new Error('Runtime bundle omitted a required entry.');
+  // This is an unpublished, disposable stage. On any write failure buildProject
+  // discards the stage and preserves the previous published build unchanged.
+  for (const [name, contents] of emitted) await writeFile(path.join(runtime, name), contents);
+  for (const entry of originals) {
+    if (!emitted.has(entry.name)) await unlink(path.join(runtime, entry.name));
+  }
+  // JSON, CJS, license files and the OG assets directory are never traversed or
+  // removed. The caller writes the normal runtime contract after prerender.
+  return { entryCount: runtimeEntryNames.length, moduleCount: emitted.size,
+    bytes: [...emitted.values()].reduce((sum, contents) => sum + contents.length, 0) };
+}

package/build/compiler.mjs

@@ -12,6 +12,7 @@ import { incrementalBuild } from './incremental.mjs';
 import { webpackGraph } from './webpack-graph.mjs';
 import { turbopackRules, sourceReader } from './turbopack-conditions.mjs';
 import {withSourceMaps,configureSourceMaps,inlineSourceMap} from './source-maps.mjs';
+import { optimizeImportsPlugins } from './optimize-imports.mjs';
 
 let validateOptions;
 const compilation = new AsyncLocalStorage();
@@ -20,7 +21,7 @@ export function configureCompiler(options) { Object.assign(compilation.getStore(
 export async function compilerSource(file, fallback) {
   return compilation.getStore()?.loaded.get(file)?.source ?? fallback ?? await readFile(file, 'utf8');
 }
-const framework = /^(?:prnext-pages-compatibility|prnext-app-(?:rsc|ssr|browser)|prnext-edge-app|prnext-edge|prnext-middleware-compatibility)$/;
+const framework = /^(?:prnext-pages-compatibility|prnext-app-(?:rsc|ssr|browser|route)|prnext-edge-app|prnext-edge|prnext-middleware-compatibility)$/;
 function condition(value, input) {
   if (value === undefined) return true;
   if (value instanceof RegExp) { value.lastIndex = 0; return value.test(input); }
@@ -120,6 +121,7 @@ export async function validateCompilerConfig(config, root, {dev=false,edge=false
 }
 export async function build(options) {
   const state = compilation.getStore();
+  if ((options.plugins || []).some(plugin => framework.test(plugin.name))) options = { ...options, plugins: optimizeImportsPlugins(options.plugins, state?.config?.experimental?.optimizePackageImports) };
   // esbuild's shared service dispatches callbacks from its own async context.
   // Re-enter this build so transforms never inherit another project's map mode,
   // action registry or configuration from the first service invocation.