@thomas.f/prnext 0.1.18-alpha → 0.1.20-alpha

package/compat/index.d.ts

@@ -14,6 +14,8 @@ export interface InstantSample {
 export type InstantConfig = boolean | { level?: 'warning' | 'experimental-error'; unstable_samples?: InstantSample[]; unstable_disableValidation?: true; unstable_disableDevValidation?: true; unstable_disableBuildValidation?: true };
 
 export interface ReactCompilerOptions {
+  /** Babel by default. The native Oxc backend is experimental and opt-in. */
+  backend?: 'babel' | 'oxc';
   compilationMode?: 'infer' | 'annotation';
   panicThreshold?: 'none' | 'critical_errors' | 'all_errors';
   /** PRNext requires matching React 19 peers. */
@@ -121,6 +123,8 @@ export interface Rewrite extends CustomRoute { destination: string }
 export type ConfigRedirect = CustomRoute & Redirect;
 /** Implemented project options. Unsupported behavior-changing options fail the build. */
 export interface NextConfig {
+  /** Public origin and transport peers permitted to set X-Forwarded-Host/Proto. */
+  server?: {publicOrigin?: string; trustedProxies?: readonly string[]};
   /** PRNext only. CLI > environment > build configuration > profile.
    * 0 disables the corresponding retirement; keepWarm retains one lane per used host.
    */
@@ -131,6 +135,10 @@ export interface NextConfig {
   workerPreload?: false | { routes: string[]; maxRssMb?: number; timeoutMs?: number };
   /** Keep bounded previous public hashed assets. false disables carry-over. Defaults: one hour, two generations, 64 MiB. */
   deploymentRetention?: false | {maxAge?: number; maxGenerations?: number; maxBytes?: number};
+  /** Common disk budget for regenerable compiler caches, in bytes (default 256 MiB).
+   * Applied after builds; active dev sessions/workers can defer reclamation.
+   * Runtime data, invalidations, page and image caches are excluded. */
+  compilationCache?: {maxDiskSize?: number};
   /** PRNext production prerender processes; maxMemoryMb bounds their combined observed memory. */
   prerender?: {workers?: number; maxMemoryMb?: number};
   /** Explicit App route patterns that must produce complete static HTML without browser JavaScript. */
@@ -167,7 +175,20 @@ export interface NextConfig {
     implementation?: 'sass' | 'sass-embedded';
     [option: string]: unknown;
   };
-  experimental?: { nextScriptWorkers?: boolean; optimizePackageImports?: string[]; proxyClientMaxBodySize?: number | string; serverActions?: true | { allowedOrigins?: string[]; bodySizeLimit?: number | string } };
+  experimental?: {
+    nextScriptWorkers?: boolean;
+    /** App Router development only; compile literal client imports on first use. */
+    lazyDynamicImports?: boolean;
+    /** Start App Route Handlers before upload EOF; mutations must handle aborted uploads. */
+    streamingRequestBodies?: boolean;
+    /** Serve certified public PPR document shells before starting Node. Requires cacheComponents. */
+    nativePprShell?: boolean;
+    /** Bound independent production CSS builds after graph discovery. Disabled by default. */
+    parallelBuilds?: boolean | {maxWorkers?: number; maxMemoryMb?: number};
+    optimizePackageImports?: string[];
+    proxyClientMaxBodySize?: number | string;
+    serverActions?: true | {allowedOrigins?: string[]; bodySizeLimit?: number | string};
+  };
   trailingSlash?: boolean;
   skipTrailingSlashRedirect?: boolean;
   skipMiddlewareUrlNormalize?: boolean;
@@ -216,6 +237,7 @@ export interface StaticBuildOptions {
 }
 export interface ReactCompilerReport {
   version: 1;
+  backend?: 'babel' | 'oxc';
   compilerVersion: string | null;
   enabled: boolean;
   buildId: string | null;
@@ -227,6 +249,7 @@ export interface ReactCompilerReport {
   summary: {files: number; functions: number; optimized: number; skipped: number; errors: number; diagnostics: number; mixed: number; transforms: number; cacheReuses: number};
   files: Array<{
     file: string; transforms: number; cacheReuses: number; targets: string[]; notes: string[];
+    diagnostics?: Array<{kind: 'CompileError' | 'CompileDiagnostic'; status: 'error' | 'diagnostic'; reason: string | null; category: string | null; targets: Array<'browser' | 'node' | 'edge' | 'unspecified'>}>;
     functions: Array<{
       name: string | null;
       start: {line: number; column: number} | null;

package/compat/link.cjs

@@ -21,11 +21,11 @@ const Link = React.forwardRef(function Link({ href, as, children, replace, scrol
   const source = formatUrl(href);
   const requestPrefetch = React.useCallback((priority = 'intent') => {
     if (prefetch === false || process.env.NODE_ENV !== 'production') return;
-    if (app?.router.partialPrefetch) app.router.prefetch(target, { priority, full: prefetch === true });
+    if (app && (app.router.partialPrefetch || prefetch === true)) app.router.prefetch(target, { priority, full: prefetch === true });
     if (!app && pages) void pages.prefetch(source, as ? target : undefined, { locale, priority }).catch(() => {});
   }, [app, pages, source, target, as, locale, prefetch]);
   React.useEffect(() => {
-    if ((app ? !app.router.partialPrefetch : !pages) || prefetch === false || process.env.NODE_ENV !== 'production' || typeof IntersectionObserver === 'undefined' || !anchorRef.current) return;
+    if ((app ? !app.router.partialPrefetch && prefetch !== true : !pages) || prefetch === false || process.env.NODE_ENV !== 'production' || typeof IntersectionObserver === 'undefined' || !anchorRef.current) return;
     const observer = new IntersectionObserver(entries => {
       if (entries.some(entry => entry.isIntersecting)) { observer.disconnect(); requestPrefetch('viewport'); }
     }, { rootMargin: '200px' });

package/compat/navigation-authorization.cjs

@@ -1,9 +1,16 @@
 'use strict';
 const { createHmac } = require('node:crypto');
+function developmentNavigationSecret(actionKey) {
+  if (typeof actionKey !== 'string' || !actionKey) return undefined;
+  // The compiler retains this private key across generations of one dev
+  // session. Derive a separate purpose key so worker replacement cannot look
+  // like an account change, without publishing or reusing the encryption key.
+  return createHmac('sha256', actionKey).update('prnext:development:navigation-authorization:v1').digest('hex');
+}
 function navigationAuthorization(context, secret, cookieNames) {
   if (!secret || context?.staticState) return undefined;
   const names = cookieNames === undefined ? null : new Set(cookieNames);
   const cookies = context.cookies.getAll().filter(cookie => !names || names.has(cookie.name)).map(({ name, value }) => [name, value]).sort((a, b) => a[0].localeCompare(b[0]));
   return createHmac('sha256', secret).update(JSON.stringify([cookies, context.headers.get('authorization') || ''])).digest('hex');
 }
-module.exports = { navigationAuthorization };
+module.exports = { navigationAuthorization, developmentNavigationSecret };

package/docs/ai/compatibility.md

@@ -18,6 +18,13 @@ transpilation, image/font tooling and caching deserve targeted build and browser
 tests. Support for one configuration shape does not imply support for all
 upstream plugin behavior.
 
+When moving from 0.1.19-alpha, use the installed
+[upgrade checklist](deployment.md#upgrading-from-0119-alpha): rebuild matching
+artifacts, configure the public HTTPS origin and proxy trust, verify strict
+account transitions and review saved persistent health routes. Storage cleanup
+must preserve runtime data and invalidation history. Experimental performance
+options remain independent and opt-in.
+
 ## Instrumentation and tracing
 
 Use a single `instrumentation.ts`, `.js`, `.mjs` or `.cjs` at the project root
@@ -132,6 +139,66 @@ new source files and configuration changes restart the native watch generation.
 adding its generated declaration to the config. Compiler support does not imply
 that every application is ready for TypeScript 7's own language/config changes.
 
+## Experimental performance paths
+
+These options are independent and disabled by default. Enable them in the
+application's existing configuration, then qualify its actual workflows:
+
+```js
+export default {
+  cacheComponents: true,
+  experimental: {
+    nativePprShell: true,
+    streamingRequestBodies: true,
+    parallelBuilds: {maxWorkers: 4, maxMemoryMb: 1024},
+  },
+};
+```
+
+`nativePprShell` lets Rust send the exact certified build shell before starting
+Node, then resume its React continuation. The initial implementation covers
+concrete App PPR document GETs without query strings, cookies, authorization,
+middleware, rewrites, base paths, router-state/Flight/prefetch headers or CSP
+nonces. Generic parameter shells, Edge, external caches and unsupported requests
+keep the ordinary Node path. Prefixes and artifacts have checked hashes and
+bounded sizes; continuations use a private transport field, never an HTTP flag.
+Responses remain private and no-store. The cache generation must still be zero
+and the build artifact unexpired: any persisted invalidation disables this build
+snapshot optimization, including across server restarts. It does not disable
+PPR itself or invalidate an already committed response. Requests already using
+a snapshot finish with that same artifact when an invalidation races them.
+
+`streamingRequestBodies` makes `Request.body` available to Node App Route
+Handlers before upload EOF. It negotiates its own protocol capability and sends
+at most one 64 KiB frame per reader credit. Unsupported workers use the existing
+buffered path. Server Actions, Pages APIs and middleware-buffered requests retain
+their previous buffering behavior. Streaming handlers can begin application
+effects before a truncated or excessive upload is rejected: validate the input
+and complete authorization before committing a mutation. The total request limit
+remains 32 MiB. Existing ingress byte reservations are preserved; this feature
+does not promise a smaller V8 heap or higher memory admission concurrency. A
+cancelled or early-returned upload closes its single-use lane without replaying
+the mutation, while retaining the healthy Node host.
+
+`parallelBuilds` freezes App stylesheet plans after dependency discovery,
+deduplicates outputs and emits independent jobs with deterministic linking.
+Graph discovery itself remains ordered. Concurrency is bounded by CPU count,
+available memory and the configured worker/budget limits. `maxWorkers` accepts
+1–8; `maxMemoryMb` accepts 256–8192 and is an admission estimate, not a hard RSS
+limit for third-party code. Custom webpack/loaders, custom PostCSS pipelines and
+Sass callbacks retain serial execution. A failed job stops new admission and
+settles started jobs before the staging build is discarded; the last published
+build is preserved. An enabled build records its actual stylesheet job count
+and selected concurrency in `manifest.buildParallelism`.
+
+Development refreshes can also target the routes that import a changed Server
+Action or its transitive dependencies. Certification uses both dependency
+graphs before and after a change. An unrelated tab still applies a deferred
+generation before navigating to a changed route. Unknown or incomplete graphs,
+binding/runtime/route changes, global configuration, rewrites/middleware,
+internationalized or parallel/intercepting routing retain a global refresh.
+Server generations still publish as a whole; pending mutations are never replayed.
+
 ## React Compiler
 
 Enable the bundled official React Compiler in the project's existing config:
@@ -142,7 +209,7 @@ export default {
 };
 ```
 
-No separate compiler installation is required. The default is disabled;
+The default Babel backend needs no separate compiler installation. The default is disabled;
 `reactCompiler: false` preserves the uncompiled component path. Enabled builds
 optimize project-owned browser components in both Pages and App applications,
 in development and production. App Client Components also use the transform in
@@ -153,17 +220,43 @@ Components, Server Action modules, PRNext internals, generated entrypoints and
 npm packages are not compiled. Keep the matching React 19 peer versions required
 by the installed framework.
 
-Ordinary `.mts`/`.cts` hook helpers can be optimized; server/client directives
-in those extensions remain unsupported. Decorated `.mts`/`.cts` utility modules
+With the default Babel backend, ordinary `.mts`/`.cts` hook helpers can be
+optimized; server/client directives in those extensions remain unsupported.
+Decorated `.mts`/`.cts` utility modules
 keep their native compilation path while importing React components can still
 be optimized.
 
 For gradual adoption, use `reactCompiler: { compilationMode: 'annotation' }`, then
 put `"use memo";` at the beginning of each component or hook to optimize. In
 either mode, `"use no memo";` excludes an individual function. Supported object
-options are `compilationMode: 'infer' | 'annotation'`,
+options are `backend: 'babel' | 'oxc'`, `compilationMode: 'infer' | 'annotation'`,
 `panicThreshold: 'none' | 'critical_errors' | 'all_errors'` and `target: '19'`.
-Defaults are `'infer'`, `'none'` and `'19'`; other fields are rejected.
+Defaults are Babel, `'infer'`, `'none'` and `'19'`; other fields are rejected.
+
+The experimental native Rust backend is an explicit alternative:
+
+```sh
+npm install --save-dev oxc-transform-react@0.157.0
+```
+
+```js
+export default {
+  reactCompiler: { backend: 'oxc' },
+};
+```
+
+Oxc is an optional peer, so ordinary Babel builds do not install its compiler,
+WASM distribution or native binding. Run the installation above in the application
+project on the build machine, with optional platform dependencies enabled. A
+global CLI also resolves this project-local peer. This option
+requires the native binding; an absent or incompatible compiler, missing binding
+or compilation failure fails explicitly. PRNext never silently changes the backend. JSX remains available
+to the existing graph compiler, while this backend removes TypeScript syntax.
+App Client Component server rendering uses Oxc's SSR output; browser graphs use
+its client output. The same project boundaries and Server Action exclusions
+apply. Source maps, loader maps and the existing Fast Refresh pipeline remain
+part of the compilation path. Unsupported options are rejected rather than
+passed through to the native compiler.
 
 After a successful build, inspect the compiler's actual results:
 
@@ -172,8 +265,8 @@ prnext compiler
 prnext compiler --json
 ```
 
-The report names observed functions, their project-relative files, optimization
-or skip status, and the compiler's reasons. These are transform decisions;
+For Babel, the report names observed functions, their project-relative files,
+optimization or skip status, and the compiler's reasons. These are transform decisions;
 server-code removal and tree shaking can later omit a function from the browser
 bundle. Cached transforms retain their
 diagnostics and are identified as reused. Browser and server graphs do not
@@ -183,6 +276,12 @@ complete application coverage. Disabled compilation is reported explicitly.
 The report describes the last successful build, stays outside public assets and
 does not include source code. A failed build preserves the previous report.
 
+The Oxc report identifies the backend and package version, records native
+diagnostics at file scope, and states that function optimization totals are
+unavailable: its API does not expose Babel's function-success events. This is
+not a count of zero optimized functions. Cached native diagnostics are replayed;
+cache identities include the backend, compiler version and client/SSR mode.
+
 The compiler can skip code that cannot be safely optimized. Follow the Rules of
 React and check actual behavior rather than assuming every component was
 compiled. It reduces repeated component work; it does not guarantee faster
@@ -192,6 +291,10 @@ production build with the option enabled and disabled. Compilation adds build
 work; PRNext caches pure transforms with their compiler version and settings.
 
 See the [official React Compiler documentation](https://react.dev/learn/react-compiler).
+The [Oxc React Compiler guide](https://oxc.rs/docs/guide/usage/transformer/react-compiler.html)
+describes the experimental backend. Measure compilation and application behavior
+with the selected backend before adopting it; selecting Rust alone is not a
+measured speedup for a project.
 
 Only explicit private Next.js import adapters are supported. Do not add arbitrary
 `next/dist/...` imports or install another Next runtime to satisfy one: isolate
@@ -236,6 +339,29 @@ by silently adding `--force` or `--legacy-peer-deps`.
 can run project code, and installed custom loaders still require a real build.
 The audit is not a sandbox for untrusted projects.
 
+The version 2 JSON report follows static imports from project sources into the
+installed packages they reference. It checks explicit PRNext adapters and their
+statically declared named exports, and includes the importing file, line and
+import chain when a dependency uses an unavailable API. It resolves selected
+Node, browser and React Server Component package conditions, including workspace
+symlinks, without importing those package modules. Unreferenced packages are not
+enumerated. Runtime branches, custom loader output and every possible bundler
+condition remain outside this check.
+
+A module-level `use server` directive is a server boundary even when a Client
+Component reaches it through a re-export. Its dependencies are still audited in
+the server context. A client dependency on a Node builtin needs an actual browser
+implementation; package `browser` mappings and installed shims are resolved
+before diagnosing it. Custom configuration aliases still require a build with
+that application's configuration.
+
+`evidence.state: "checked"` means the selected static graph was inspected, not
+that migration is certified. `"unknown"` identifies unresolved/computed imports,
+loader inputs or incomplete coverage. The graph is bounded to 2,000 modules,
+12,000 imports, 32 MiB of source reads and 32 import hops. Hitting a limit leaves
+the remaining coverage unknown. `ok` means no blocking diagnostic was found;
+inspect warnings and coverage even when it is true.
+
 ## Compare running applications
 
 Start the original application and the candidate on separate available ports.
@@ -258,6 +384,60 @@ in a real browser, test authorized and unauthorized states, and run the existing
 application tests. Keep the original setup available until the candidate is
 actually verified. Timings from this comparison are not controlled benchmarks.
 
+## Run application browser scenarios
+
+An explicit browser option can run the application's own assertions against
+each server. Install Playwright and its Chromium browser in the application
+using its normal development setup; PRNext never installs them for this check.
+Provide a trusted `.mjs`, `.cjs` or `.js` module inside the application directory:
+
+```js
+// migration.scenarios.mjs
+export default [
+  {
+    async run({page, baseURL}) {
+      await page.goto(`${baseURL}/sign-in`);
+      await page.getByLabel('Email').fill(process.env.MIGRATION_TEST_EMAIL);
+      await page.getByLabel('Password').fill(process.env.MIGRATION_TEST_PASSWORD);
+      await page.getByRole('button', {name: 'Sign in', exact: true}).click();
+      await page.getByRole('heading', {name: 'Dashboard', exact: true}).waitFor();
+      await page.getByRole('button', {name: 'Save note', exact: true}).click();
+      await page.getByText('Note saved', {exact: true}).waitFor();
+      await page.getByRole('button', {name: 'Sign out', exact: true}).click();
+      await page.getByRole('heading', {name: 'Sign in', exact: true}).waitFor();
+    },
+  },
+];
+```
+
+Replace the URLs and accessible names with the application's real controls.
+Supply dedicated test account values through the command's environment rather than
+command arguments or source files. Use isolated test databases: these explicit
+callbacks execute application code and can submit forms or mutate data.
+
+```sh
+prnext migrate --check --against http://localhost:3000 --candidate http://localhost:3001 --routes paths.json --browser-scenarios migration.scenarios.mjs --timeout 15000 --json
+```
+
+Only this option loads the scenario module and starts a browser. It requires
+the application's installed `playwright` or `@playwright/test`. Each callback
+receives a new isolated browser context for each target. Assert observable
+behavior inside the callback; its return value is ignored. A callback that
+fulfills passes for that target, and a thrown assertion fails. Both targets
+must pass independently; equal durations or response samples are not used to
+infer browser equivalence.
+
+The report records scenario numbers, targets and pass/fail results. It excludes
+application console output, raw error messages, request data, cookies and
+screenshots. Read or debug the original application test separately when a
+generic failure needs investigation. Keep credentials out of assertion labels
+and application-managed artifacts too. An unavailable browser or incomplete run
+is reported as unknown. There are at most 20 scenarios, a 100–60,000 ms budget
+per callback, a bounded startup period and a five-minute maximum for the worker.
+A timeout closes its context and ends the run before another target starts.
+The worker also closes its owned browser when it finishes. This is explicit
+execution of trusted test code, not a sandbox for an untrusted module.
+
 ## Boundaries that often matter
 
 React server/client directives in `.mts`/`.cts` are rejected; use `.ts`/`.tsx`.

package/docs/ai/deployment.md

@@ -8,12 +8,90 @@ Build with the installed PRNext and run the resulting trusted output with its
 matching runtime:
 
 ```sh
+prnext check --production
 prnext typecheck
 prnext build
 prnext output --json
 prnext start --hostname 127.0.0.1 --port 3000
 ```
 
+### Upgrading from 0.1.19-alpha
+
+Install matching framework/native versions, then rebuild and restart the complete
+application or standalone output. Keep Node and the React protocol peers aligned
+with this package's metadata. Existing compiler entries are reused only when
+their identities match; never delete `data.sqlite3` or invalidation history to
+perform an upgrade. Read the storage section below before pruning compiler caches.
+
+Persistent apps need a supervisor restart too. In a maintenance window for the
+whole `PRNEXT_PM_HOME`, run `prnext pdown` with that same home before replacing
+packages. It stops all managed apps and preserves saved settings and enabled
+entries; `prestart` alone keeps the already loaded supervisor code. Update and
+rebuild the installations that must return with 0.1.20, then launch `pstart` or
+`prestart` through the new CLI. It also restores all enabled entries, with their
+saved binary paths and health routes. Check `pstatus` and real health responses;
+a global CLI update does not replace each app's package or binary. Keep independent
+lifecycles in separate homes.
+
+Set `server.publicOrigin` to the external HTTPS origin and `server.trustedProxies`
+to the immediate proxy's IP/CIDR addresses. The configured origin wins; forwarded
+host/protocol headers are trusted only from those peers. Rebuild after config
+changes and check redirects, secure cookies and authentication callbacks over
+the actual public URL. This does not establish a forwarded client-IP chain.
+
+Run production preflight, then test account A → sign out → account B with the
+actual `navigationCache.authCookies`, including shared layouts and browser
+history. Changed or unknown strict identities require a fresh document; cached
+PPR previews wait for fresh identity. Authorize protected reads and writes in
+the application as before.
+
+Use a dedicated complete HTTP 200 application health response for database/service
+readiness. `/_prnext/health` checks native readiness only; redirects no longer
+pass persistent health checks. Previously saved applications keep their health
+path, so a redirecting `/` must be replaced in the saved persistent settings.
+Observe the post-switch rollback window and exercise an explicit idempotent
+retry; a lost response can follow a successful write, and mutations are never
+automatically replayed. Keep schema changes compatible with the previous server.
+
+### Production preflight
+
+Run `prnext check --production --json` to collect deployment diagnostics without
+building or rewriting the application. It evaluates the production config and
+environment files, restores the calling process environment afterward, and checks
+installed dependencies, route conventions, the public origin, proxy trust,
+authentication retention settings and active experimental options. JSON diagnostics
+include `code`, `path`, `severity` and an action where one is needed. Errors fail
+the command; warnings require review and do not change its exit status.
+
+If a build already exists, preflight also compares its public origin, proxy and
+authentication retention settings with the current config and rejects a development artifact. Rebuild after
+changing deployment settings: `prnext start` reads the selected artifact and does
+not reevaluate the source configuration. Missing output is informational before
+the first build; unreadable existing metadata requires review.
+
+For authenticated App Router applications, explicitly list every session cookie
+name, including HTTPS variants used by the authentication library:
+
+```js
+export default {
+  navigationCache: {
+    authCookies: ['session-cookie-name', '__Secure-session-cookie-name'],
+  },
+};
+```
+
+Replace these example names with the application's actual cookies; PRNext does
+not infer authentication from cookie names. This enables strict retained-page
+state resets when the server's authorization identity changes. Test account A →
+sign out → account B with both active and retained pages, and confirm that private
+drafts disappear. Public applications can review the guidance or disable page
+retention with `navigationCache: false`.
+
+A successful preflight checks configuration, not external services or application
+authorization. Qualify the final build over public HTTPS, including authentication,
+health checks, failure recovery and rollback. Experimental warnings identify the
+options that need workload-specific validation; they are not performance claims.
+
 The default build directory is `.prnext`; `distDir` can change it. The private
 project output selector is `.prnext-output.json`. Do not assume `.next` layout,
 run `next start` on a PRNext build or hand-edit its manifests to bypass runtime
@@ -254,6 +332,69 @@ an explicit choice, not a reason to print credentials or copy `.env` into assets
 
 ## Observe before tuning
 
+### Installation and disk storage
+
+The default installation includes Babel React Compiler support. The Oxc React
+Compiler backend is an optional peer installed explicitly; read the
+[compatibility guide](compatibility.md) before selecting it. Keep optional native
+platform dependencies enabled. The framework's internal Fontkit bundle includes
+its provenance and dependency licenses under `vendor/fontkit`; applications do
+not need a separate Fontkit dependency for `next/font`.
+
+Production builds retain one OpenGraph renderer when needed. A bounded analysis
+of the compiled server graph may omit it only when the application can be
+certified not to use `ImageResponse`. Development, Edge, unknown external modules
+and computed loading keep it. No configuration change is needed. Deploy the
+standalone output alone when using `output: 'standalone'`; copying the complete
+ordinary build beside it duplicates those artifacts.
+
+Compiler caches share a **256 MiB** retention budget per project:
+
+```js
+export default {
+  compilationCache: {maxDiskSize: 128 * 1024 * 1024}, // bytes, 0–4 GiB
+};
+```
+
+PRNext applies the policy after a build, including failures, and after a clean
+development shutdown. It is a retention target, not a hard filesystem quota:
+active development, pinned V8 workers, busy files or an incomplete bounded scan
+can defer reclamation. Existing per-cache limits still apply. Eviction can make
+the next build slower; evicted downloaded fonts need network access again.
+Large JSON entries use bounded, checksummed compression; old raw records remain
+readable, and corrupt/incompatible records are cache misses.
+
+Inspect and preview changes without executing application configuration:
+
+```sh
+prnext cache --json
+prnext cache --prune --dry-run --max-bytes 67108864 --json
+prnext cache --prune --max-bytes 67108864
+```
+
+The CLI reads the policy saved by the last build. `--max-bytes` overrides only
+that purge; `0` removes eligible compiler records. Statistics cover recognized
+framework cache files, excluding unknown paths; `scanComplete: false` means a
+lower bound and prevents purging from an incomplete snapshot. Stop development
+before purging. Concurrent builds are protected by the publisher lock, active
+managed workers pin their namespace, and failed deletions can be retried.
+
+These commands never remove runtime data, `data.sqlite3`, page/image indexes,
+invalidation generations, tags or fill leases. Never delete/reset the data
+database to reclaim compiler storage: that can lose invalidation history. The
+runtime instead performs small incremental SQLite reclamation steps and bounded
+orphan-file maintenance on its own timer. Existing SQLite databases without
+incremental auto-vacuum retain their existing format; no full VACUUM runs on a
+request. Older page files without a verifiable reader lease are retained.
+
+Builds and dev sessions also journal their owned temporary directories. After a
+crash, later starts reclaim eligible entries only after a grace period and proof
+that their local owner/workers have exited. Unknown directories, foreign-host or
+unverifiable owners and uncommitted build backups are kept for recovery. Do not
+remove a recovery backup until the selected build has been checked.
+
+### Runtime observations
+
 Production rendering, API and regeneration admission use bounded queues grouped
 by resolved route pattern. Different parameter values share one pattern's
 waiting budget. Waiting patterns take turns as capacity becomes available;

package/docs/ai/quickstart.md

@@ -13,6 +13,11 @@ react-server-dom-webpack 19.3.1**. Its Node engine range is
 `^22.23.4 || ^24.22.1 || >=26.12.1`. Check the installed package manifest when
 upgrading; these requirements may change between releases.
 
+Optional peers are installed only for the features that use them:
+`@redis/client` for [shared Redis caching](data.md), and `oxc-transform-react`
+for the [experimental Oxc React Compiler](compatibility.md#react-compiler).
+The default Babel compiler needs no additional compiler installation.
+
 Published releases include a matching native component through optional
 dependencies for Windows, macOS and glibc Linux, on x64 and ARM64. Keep optional
 dependencies enabled. Consumers do not need Rust; building PRNext from its source

package/docs/ai/routing.md

@@ -88,6 +88,9 @@ Client Components can participate in server rendering. Read `window`,
 `useEffect`, not unconditionally during render. Server and first browser render
 must agree. Use `.ts` or `.tsx` for `'use client'` and `'use server'` boundaries;
 PRNext rejects those directives in `.mts`/`.cts` instead of silently misbundling.
+The migration audit reports these unsupported boundaries too. It also checks
+`server-only` and `client-only` markers through imported helpers, respecting
+module-level Server Action boundaries and Node Route Handlers.
 
 ## Navigation and typed routes
 
@@ -110,6 +113,14 @@ without connection information retain bounded prefetching. `prefetch={false}`
 disables Link speculation, including hover and focus. None of these policies
 blocks a real click or changes authorization and private-data checks. App Link
 automatic prefetching retains its existing partial-rendering requirement.
+Set `prefetch={true}` to warm the full destination explicitly in an ordinary
+App Router application without `cacheComponents`. The same network limits
+apply, and development does not prefetch. Full prefetch warms modules and data;
+the click still sends a fresh server request before showing the destination.
+This includes prerendered pages whose access is controlled by a proxy: a
+prefetched response cannot authorize a later navigation after an HttpOnly
+cookie changes. Leave the prop unset to keep automatic behavior, or use `false`
+to disable speculation.
 
 ### Connection loss during App navigation
 

package/docs/ai/troubleshooting.md

@@ -2,6 +2,70 @@
 
 [AI documentation index](../../AI.md)
 
+## Compile large client imports only when used in development
+
+For App Router applications, the explicit experimental option below keeps
+literal client `import()` targets outside the initial browser graph. It defers
+their transformation and compilation, rather than only downloading an already
+compiled chunk later.
+
+```js
+// prnext.config.mjs
+export default {
+  experimental: { lazyDynamicImports: true }
+};
+```
+
+The option affects `prnext dev` only. Production keeps its ordinary dynamic
+chunks and does not use a development compilation endpoint. SSR also keeps its
+normal behavior. A `next/dynamic` component with `{ ssr: false }` is a useful
+candidate for an editor or other large browser-only feature; an import needed
+by SSR still needs its server compilation.
+
+On first use, the development server compiles the requested subgraph, publishes
+its immutable assets, and loads its CSS before resolving the import. Already
+loaded ESM dependencies are reused through their original module URLs, keeping
+shared objects and live bindings. Once activated, the module participates in
+subsequent JavaScript and stylesheet updates. A failed compilation can be
+requested again after correcting its source.
+
+Activated styles remain loaded for the generation, including when parallel
+slots select their own styles. Prefer CSS Modules or selectors scoped to the
+deferred feature when its global styles should not affect other components.
+
+The initial scope is App Router applications using the native compiler, with
+same-origin assets and no webpack hook or custom loaders. Literal imports from
+project `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts` and `.tsx` sources are eligible;
+computed imports, import attributes, literal requests containing `?` or `#`,
+imports inside installed packages and typed `.mts`/`.cts` helpers keep the
+ordinary compiler behavior. The compiler keeps the distinct module identities
+of those literal query and fragment imports. If an alias or a transitive
+dependency introduces a resolved query or fragment suffix inside a deferred
+graph, activation returns an explicit error
+before reusing any shared export bridge. Disable the option for that graph;
+query and fragment identities in deferred graphs are not currently supported.
+The compiler does not silently duplicate a shared CommonJS dependency: that
+case returns an explicit error. Convert that shared dependency to ESM or disable
+the option.
+Server Actions first introduced only by a deferred graph also require a static
+import or the ordinary compiler, because the running server implementation
+cannot be extended by publishing browser assets alone.
+
+There are at most 128 registered imports and 4,096 static JavaScript dependency
+identities per generation. Deferred assets have a cumulative 128 MiB budget per
+active generation. Existing development request and generation limits still
+apply. Public requests contain opaque registered IDs, never source filenames;
+an unknown ID cannot initiate a deferred compilation. Static ESM export bridges
+have their own startup cost, so measure your application's initial build and
+first-use delay before keeping the option enabled.
+
+Deferred JSON imports share their native ESM namespace and default object across
+importers. Deferred assets are written outside the served directory and published
+as complete immutable files. This experimental path requires hardlinks within
+the development generation's filesystem; disable `lazyDynamicImports` if that
+filesystem cannot create them. A failed activation keeps existing assets intact
+and conservatively accounts for any publication whose outcome is uncertain.
+
 ## Collect a useful failure
 
 Read the installed version, command, working directory, Node version, manager,
@@ -54,6 +118,21 @@ repair. Verify the interactive result after the change.
 
 ## HMR and cache failures
 
+When an Action overlaps a refresh or navigation, its mutation result remains
+independent from whether its older render is applied. A newer interaction can
+release a superseded development commit wait; it never replays the mutation.
+
+For a development state publication failure, keep the private
+`.prnext-dev/<session>/diagnostics/state-publication.json` receipt. It records the
+operation phase, error code, bounded rename attempts and last published sequence,
+without source contents or a full source path. Windows transient rename failures
+are retried for up to two seconds; a permanent failure preserves the previous
+complete state file. After a replacement runtime has activated, publication
+failure still retires obsolete runtimes through the gateway and keeps the
+existing three-generation snapshot bound. In-flight requests drain before
+their old runtime closes. Record the actual code and phase instead of assuming
+an antivirus or file watcher caused the lock.
+
 Development compiles requested routes and preserves state for compatible edits;
 config/environment, custom Document or incompatible module changes can reload
 the document. Production prerendering and compression are not development HMR.