@thomas.f/prnext 0.1.19-alpha → 0.1.21-alpha

package/compat/flight-delta.cjs

@@ -3,7 +3,7 @@
 const WINDOW = 32, MAX_VALUE = 2 * 1024 * 1024, MAX_RESPONSE = 16 * 1024 * 1024;
 const TYPE = 'application/x-prnext-flight-delta';
 const MAGIC = new Uint8Array([80,82,68,49]);
-const BLOCK_BYTES = 32 * 1024, MAX_COMMANDS_PER_CHUNK = 256, MAX_COMMANDS = 2048;
+const BLOCK_BYTES = 32 * 1024, MAX_COMMANDS_PER_CHUNK = 256, MAX_COMMANDS = 2048, MAX_CAPTURE_PARTS = 2048;
 let POWER = 1; for(let n=1;n<WINDOW;n++) POWER = Math.imul(POWER,31) >>> 0;
 function hash(bytes,offset) { let result=0; for(let n=0;n<WINDOW;n++) result=(Math.imul(result,31)+bytes[offset+n])>>>0; return result; }
 function createIndex(base) {
@@ -44,12 +44,47 @@ function blocks(parts) {
   for(const part of parts)for(let offset=0;offset<part.length;){const n=Math.min(BLOCK_BYTES-size,part.length-offset);pending.push(part.subarray(offset,offset+n));size+=n;offset+=n;if(size===BLOCK_BYTES)flush();}
   flush();return output;
 }
-function collectStream(source,{onComplete,onCancel,onFinally,capture=true}={}) {
-  const reader=source.getReader(), parts=[];let size=0,complete=false,finished=false;
+// Only the worker bridge registers streams here. Their backing allocations
+// crossed a transfer boundary, have no producer aliases, and the framework's
+// outgoing transport does not mutate or transfer them again. Arbitrary React,
+// fetch and application streams retain the defensive per-chunk copy.
+// Even an owned partial view is copied: retaining its much larger backing
+// allocation would defeat the byte-based capture limit.
+const ownedStreams=new WeakSet();
+function ownFlightStream(source){ownedStreams.add(source);return source;}
+function collectStream(source,{onComplete,onEnd,onCancel,onFinally,capture=true}={}) {
+  const owned=ownedStreams.has(source);
+  const reader=source.getReader(), parts=[];let size=0,complete=false,finished=false,cancelled=false;
   const finish=()=>{if(!finished){finished=true;onFinally?.();}};
   return new ReadableStream({
-    async pull(controller) {try{const next=await reader.read();if(next.done){complete=true;if(capture&&size<=MAX_VALUE)onComplete?.(join(parts,size));parts.length=0;finish();controller.close();return;}if(!(next.value instanceof Uint8Array))throw new Error('Invalid Flight bytes');size+=next.value.length;if(size>MAX_RESPONSE)throw new Error('Flight exceeds transport budget');if(capture&&size<=MAX_VALUE)parts.push(next.value.slice());else parts.length=0;controller.enqueue(next.value);}catch(error){parts.length=0;finish();controller.error(error);await reader.cancel(error).catch(()=>{});}},
-    async cancel(reason){parts.length=0;finish();if(!complete)onCancel?.();await reader.cancel(reason);},
+    async pull(controller) {
+      try {
+        const next=await reader.read();
+        if(cancelled)return;
+        if(next.done){
+          complete=true;
+          if(capture)onComplete?.(join(parts,size));
+          parts.length=0;onEnd?.();finish();controller.close();return;
+        }
+        const value=next.value;
+        if(!(value instanceof Uint8Array))throw new Error('Invalid Flight bytes');
+        size+=value.length;
+        if(size>MAX_RESPONSE)throw new Error('Flight exceeds transport budget');
+        if(capture){
+          // Limits include the number of retained allocations, not just their
+          // payload bytes. An abandoned capture never interrupts the response.
+          if(size>MAX_VALUE||value.length&&parts.length>=MAX_CAPTURE_PARTS){capture=false;parts.length=0;}
+          else if(value.length){
+            const wholeOwned=owned&&value.buffer instanceof ArrayBuffer&&value.byteOffset===0&&value.byteLength===value.buffer.byteLength;
+            // Buffer.slice() aliases its producer's backing allocation. The
+            // plain Uint8Array constructor always copies just the visible bytes.
+            parts.push(wholeOwned?value:new Uint8Array(value));
+          }
+        }
+        controller.enqueue(value);
+      }catch(error){parts.length=0;finish();if(cancelled)return;controller.error(error);await reader.cancel(error).catch(()=>{});}
+    },
+    async cancel(reason){cancelled=true;parts.length=0;finish();if(!complete)onCancel?.();await reader.cancel(reason);},
   },{highWaterMark:0});
 }
 async function deltaStream(source,base,{assess}={}) {
@@ -58,10 +93,10 @@ async function deltaStream(source,base,{assess}={}) {
   // A short first chunk always selects ordinary Flight. Do not build a base
   // index that this response cannot use, or wait for a later streaming chunk.
   let index=first.value.length>=WINDOW&&base instanceof Uint8Array&&base.length<=MAX_VALUE?createIndex(base):null;
-  const profitable=(raw,frames,initial)=>frames&&frames.reduce((n,b)=>n+b.length,0)+(initial?5:1)<raw.length*0.9&&(!assess||assess(raw,join(initial?[MAGIC,...frames,new Uint8Array([2])]:frames,frames.reduce((n,b)=>n+b.length,0)+(initial?5:0)))===true);
+  const profitable=async(raw,frames,initial)=>frames&&frames.reduce((n,b)=>n+b.length,0)+(initial?5:1)<raw.length*0.9&&(!assess||await assess(raw,join(initial?[MAGIC,...frames,new Uint8Array([2])]:frames,frames.reduce((n,b)=>n+b.length,0)+(initial?5:0)))===true);
   const firstFrames=index&&first.value.length>=WINDOW?encodeChunk(first.value,base,index):null;
   let useDelta;
-  try{useDelta=!!profitable(first.value,firstFrames,true);}catch(error){await reader.cancel(error).catch(()=>{});throw error;}
+  try{useDelta=!!(await profitable(first.value,firstFrames,true));}catch(error){await reader.cancel(error).catch(()=>{});throw error;}
   let pending=useDelta?blocks([MAGIC,...firstFrames]):[first.value], pendingAt=0,ended=false,tail=false,commands=firstFrames?.commands||0;
   if(!useDelta){base=undefined;index=undefined;}
   return {delta:!!useDelta,body:new ReadableStream({
@@ -69,7 +104,7 @@ async function deltaStream(source,base,{assess}={}) {
       if(pendingAt===pending.length&&!ended){pending=[];pendingAt=0;const next=await reader.read();
         if(next.done){ended=true;if(useDelta&&!tail)pending=[new Uint8Array([2])];}
         else if(useDelta&&!tail){const encoded=encodeChunk(next.value,base,index);commands+=encoded?.commands||0;
-          if(commands>MAX_COMMANDS||!profitable(next.value,encoded,false)){tail=true;index=undefined;base=undefined;pending=blocks([new Uint8Array([3]),next.value]);}
+          if(commands>MAX_COMMANDS||!await profitable(next.value,encoded,false)){tail=true;index=undefined;base=undefined;pending=blocks([new Uint8Array([3]),next.value]);}
           else pending=blocks(encoded);
         }else pending=[next.value];
       }
@@ -134,19 +169,19 @@ function createFlightTransport() {
   let current,serial=0;
   return {
     snapshot(){return current;},
-    async response(response,base) {
+    async response(response,base,{onEnd}={}) {
       const version=++serial;
       const token=response.headers.get('x-prnext-flight-token'), headers=new Headers(response.headers);
       let source=response.body;
-      if(!source)return response;
+      if(!source){onEnd?.();return response;}
       if(headers.get('content-type')?.startsWith(TYPE)) {
         if(!base||headers.get('x-prnext-flight-base')!==base.token){await source.cancel();throw new Error('Missing Flight delta base');}
         source=decodeStream(source,base.bytes);
       }
       headers.set('content-type','text/x-component; charset=utf-8');headers.delete('content-length');headers.delete('content-encoding');
-      return new Response(collectStream(source,{capture:!!token&&/^[a-f0-9]{48}$/.test(token),onComplete:bytes=>{if(version===serial&&token&&/^[a-f0-9]{48}$/.test(token))current={token,bytes};}}),{status:response.status,statusText:response.statusText,headers});
+      return new Response(collectStream(source,{capture:!!token&&/^[a-f0-9]{48}$/.test(token),onEnd,onComplete:bytes=>{if(version===serial&&token&&/^[a-f0-9]{48}$/.test(token))current={token,bytes};}}),{status:response.status,statusText:response.statusText,headers});
     },
     clear(){serial++;current=undefined;},
   };
 }
-module.exports={TYPE,MAX_VALUE,createIndex,encodeChunk,deltaStream,decodeStream,collectStream,createFlightTransport};
+module.exports={TYPE,MAX_VALUE,createIndex,encodeChunk,deltaStream,decodeStream,collectStream,createFlightTransport,ownFlightStream};

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; /** App Router development only; compile literal client imports on first use. */ lazyDynamicImports?: 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/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/compat/runtime-sample.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+// Constructed only for opt-in diagnostics. Samples contain numeric runtime
+// counters, never application values, request context or allocation stacks.
+function createRuntimeSampler() {
+  const { PerformanceObserver, performance } = require('node:perf_hooks');
+  const { threadId, resourceLimits } = require('node:worker_threads');
+  const { getHeapSpaceStatistics } = require('node:v8');
+  let count = 0, durationMs = 0, maxPauseMs = 0;
+  let previousTime = performance.now();
+  let previousLoop = performance.eventLoopUtilization();
+  let previousCpu = threadId === 0 ? process.cpuUsage() : undefined;
+  const consume = entries => {
+    for (const entry of entries) {
+      count++;
+      durationMs += entry.duration;
+      maxPauseMs = Math.max(maxPauseMs, entry.duration);
+    }
+  };
+  const observer = new PerformanceObserver(list => consume(list.getEntries()));
+  observer.observe({ entryTypes: ['gc'] });
+  return {
+    sample() {
+      consume(observer.takeRecords());
+      const now = performance.now();
+      const loop = performance.eventLoopUtilization();
+      const eventLoop = performance.eventLoopUtilization(loop, previousLoop);
+      const { rss, heapUsed, heapTotal, external, arrayBuffers } = process.memoryUsage();
+      const young = getHeapSpaceStatistics().find(space => space.space_name === 'new_space');
+      const value = {
+        node: process.version, v8: process.versions.v8, threadId,
+        intervalMs: now - previousTime,
+        rssBytes: rss, heapUsedBytes: heapUsed, heapTotalBytes: heapTotal,
+        externalBytes: external, arrayBufferBytes: arrayBuffers,
+        youngSpaceBytes: young?.space_size ?? 0,
+        workerLimits: { ...resourceLimits },
+        gc: { count, durationMs, maxPauseMs },
+        eventLoop,
+      };
+      // CPU usage is process-wide, including all worker threads. Emit it only
+      // in the main isolate so aggregators cannot count the RSC CPU twice.
+      if (previousCpu) {
+        const cpu = process.cpuUsage();
+        value.cpu = { scope: 'process', userMicros: cpu.user - previousCpu.user,
+          systemMicros: cpu.system - previousCpu.system };
+        previousCpu = cpu;
+      }
+      previousLoop = loop; previousTime = now;
+      count = durationMs = maxPauseMs = 0;
+      return value;
+    },
+    close() { observer.disconnect(); },
+  };
+}
+
+module.exports = { createRuntimeSampler };

package/compat/use-cache.cjs

@@ -93,14 +93,17 @@ async function invokeCache(id, kind, captures, args, callback, segment = '') {
     then(_resolve, reject) { reject(new Error("searchParams cannot be read inside 'use cache'; read them outside and pass their values as arguments")); },
   };
   if (encoded.key.length > MAX_BYTES) throw new Error("'use cache' arguments exceed 2 MiB");
-  const key = createHash('sha256').update(id).update(kind).update(codec === plainCodec ? ':v8:' : ':flight:').update(encoded.key).digest('hex');
+  const format=codec===plainCodec?':v8:':codec.cacheKeyVersion==='flight-primitives-v2'?':flight-primitives-v2:':':flight:';
+  const key = createHash('sha256').update(id).update(kind).update(format).update(encoded.key).digest('hex');
   const profiles = context.cacheLife || context.manifest?.config?.cacheLife || defaults;
   const scope = { kind, profiles, life: { ...profiles.default }, explicit: new Set(), tags: new Set() };
   let producedMetadata;
   const producer = async () => runCacheScope(async () => {
     const value = await codec.render(() => callback(...encoded.values), encoded, context);
     producedMetadata = metadata(scope, context);
-    return envelope(producedMetadata, Buffer.from(value));
+    // envelope owns its result immediately; an already owned codec Buffer need
+    // not be copied into another temporary Buffer before this synchronous copy.
+    return envelope(producedMetadata, Buffer.isBuffer(value)?value:Buffer.from(value));
   }, scope);
   let bytes, handlerMetadata;
   const custom = kind !== 'private' && !context.draftMode && Object.hasOwn(configured(context), kind);

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
@@ -97,7 +104,7 @@ implemented through PRNext's generated route registry. Do not copy a full
 Next.js configuration template into a new application.
 
 The repository's reference tests build and run matching applications against
-Next.js 16.4.3, including mounted App navigation, form Actions and cookies,
+Next.js 16.4.4, including mounted App navigation, form Actions and cookies,
 metadata, Pages locale routing, redirects, APIs and selected webpack loader
 contracts. These executable examples cover specific behavior; they do not
 certify every Next.js application or plugin. `NextRequest.nextUrl` understands
@@ -105,10 +112,10 @@ data-route build IDs and locales, and request-cookie mutations synchronize the
 request header. Request cookies have different mutation results from response
 cookies; do not use them interchangeably.
 
-A locked real-application fixture additionally exercises Better Auth 1.7.14
+A locked real-application fixture additionally exercises Better Auth 1.7.15
 (email/password, session cookies and logout), Drizzle ORM 0.45.4 over SQLite
 through its proxy driver, next-intl 4.14.9 (server and client translations),
-and the MDX 3.1.1 webpack loader against Next.js 16.4.3. It covers authenticated
+and the MDX 3.1.1 webpack loader against Next.js 16.4.4. It covers authenticated
 Server Actions, user-owned rows, cookie/locale isolation, client navigation and
 Server Component `after()` callbacks. This is evidence for those workflows,
 not a guarantee for every plugin, provider or deployment configuration.
@@ -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

package/docs/ai/deployment.md

@@ -8,12 +8,93 @@ 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 an earlier 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 the old installation's `prnext pdown` with that same
+home before replacing packages. The 0.1.21 local protocol rejects an old
+supervisor rather than silently taking it over. Shutdown 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 the new version, 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. Do not stop unrelated Node processes or external
+databases, Redis, proxies and OS services as an automatic upgrade fallback.
+
+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 +335,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