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

package/docs/ai/deployment.md

@@ -0,0 +1,269 @@
+# Build and deployment
+
+[AI documentation index](../../AI.md)
+
+## React production server
+
+Build with the installed PRNext and run the resulting trusted output with its
+matching runtime:
+
+```sh
+prnext typecheck
+prnext build
+prnext output --json
+prnext start --hostname 127.0.0.1 --port 3000
+```
+
+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
+compatibility checks. PRNext's native server handles HTTP while React rendering
+uses Node workers. Published native components must match the framework version.
+
+Each production artifact also has its own deployment identity, even when
+`generateBuildId` returns a constant. App navigation, Pages data and JavaScript
+Server Actions check this identity before decoding a response. A stale GET can
+fall back to a document navigation. A stale action fails without executing or
+automatically replaying the mutation; preserve the user's work and ask them to
+reload before retrying it explicitly.
+
+When rebuilding into the same output directory, PRNext can carry forward public
+hashed assets from two previous artifacts for up to one hour, within a 64 MiB
+budget. This does not retain old server code, HTML, data responses or sessions.
+It does not coordinate independent servers or a CDN: deploy matching artifacts
+and configure the proxy to preserve the deployment headers and cache variation.
+Use `deploymentRetention: false` to disable carry-over, or configure
+`deploymentRetention: { maxAge: 3600, maxGenerations: 2, maxBytes: 67108864 }`;
+`maxAge` is in seconds. A new output directory has no previous assets to retain.
+
+For an existing reverse proxy, bind the application to loopback and configure
+the proxy according to the deployment environment. Set required production
+environment variables and exercise a real health route before switching
+traffic. Check navigation, static assets, actions and cookies over the actual
+public HTTPS origin. Changes to DNS, service managers, public access and
+production traffic need the user's deployment scope; a local build does not
+authorize them.
+
+An optional `prnext.config.mjs` with `output: 'standalone'` generates traced
+standalone output under the build directory. Follow the generated artifact's
+entrypoint (`node server.js` from its standalone directory) and preserve its
+relative files. Build for the target OS/architecture and retain compatible Node;
+a standalone bundle is not a universal executable. Read the shipped
+[build output contract](../../build/ADAPTERS.md) for artifact boundaries.
+
+## HTML rendering paths
+
+Buffered App HTML decodes UTF-8 chunks incrementally, avoiding a second aggregate
+binary copy. The existing 16 MiB response limit still applies, including to large
+chunks and multi-byte text.
+
+The default remains React's Web stream renderer. To evaluate the experimental
+Node pipeable renderer, set `PRNEXT_SSR_STREAM=node` in the server environment.
+It uses bounded backpressure and cancellation for ordinary Node App rendering.
+Partial/PPR continuations keep the Web API and their original resume state;
+Edge rendering is unchanged. Unset the variable to restore the default.
+This is a workload comparison option, not a promised performance multiplier:
+small-page CPU and larger-page timings can move in different directions.
+
+## Readiness and first-request latency
+
+`prnext start --prewarm` initializes the framework renderers before accepting
+HTTP requests. It warms one render host and its RSC isolate; additional hosts
+remain lazy. It does not call application pages, API handlers or data loaders.
+Normal instrumentation initialization still runs. Existing `workerPreload`
+configuration, if present, separately imports the application modules selected
+by that configuration. Prewarming failure prevents HTTP readiness.
+
+For a supervisor, add `--readiness-file /private/run/instance-ready.json`.
+Create its parent directory first, and use a separate path per application or
+independent instance. The atomically replaced JSON contains `ready`, `pid`,
+`address`, `generation`, and `render: 'prewarmed' | 'lazy'`. HTTP readiness alone
+does not mean a lazy React renderer is loaded. Replacement and shutdown
+coordinate through a private sidecar lock; normal shutdown removes only its
+own generation. A forced termination can leave a stale marker, so the supervisor
+must also verify the process identity and a real application health check.
+
+Idle retirement saves memory at the cost of the next render's wake latency.
+For an application that must keep its used hosts alive, explicitly pass
+`--worker-idle-seconds 0`. Prewarming is a startup operation, not periodic
+synthetic traffic, and does not silently disable retirement. Measure the first
+dynamic page as well as startup time; prewarming moves work earlier rather
+than eliminating all cold work.
+
+## Profiles under resource limits
+
+Balanced remains the default. On Linux, effective policies consider CPU quotas
+and memory ceilings at visible cgroup-v2 ancestors, as well as available CPUs.
+Speed uses a smaller nursery and admission/buffer budgets when limited to one
+CPU or at most 1 GiB memory. Balanced also lowers its budgets below 512 MiB.
+The native launcher passes its effective policy to the RSC isolate so both use
+the same resource decision. Explicit `NODE_OPTIONS` heap flags keep their precedence.
+
+Memory favors a smaller nursery and earlier idle retirement, without forcing
+V8's optimize-for-size policy. It can still trade CPU and latency for RAM.
+Classic preserves the historical policy. These settings are advisory budgets,
+not total RSS caps; use an OS/container limit for hard isolation. Explicit
+worker counts are not automatically increased to match the host CPU count.
+Compare throughput, CPU per correct response, p95 and memory together before
+choosing Speed or adding workers.
+
+## Production worker memory and recovery
+
+A production Node host can be drained when its RSS stays above an explicit soft
+budget for three one-second samples:
+
+```js
+export default { workerMemory: { maxRssMb: 512 } };
+```
+
+This is opt-in (64–65536 MiB), separate from the build's prerender budget. It
+observes process RSS, including rendering threads; it does not cap V8's heap or
+force garbage collection. Existing responses and tracked work finish on the old
+host while new work uses a replacement. At most two process generations per
+host group can overlap, including child reaping; further replacement waits for
+capacity. This is not an OS memory sandbox: a busy draining host can exceed the
+soft target. Serial maintenance workers check their budget after requests.
+Development keeps its existing worker behavior.
+
+Repeated failed Node starts and unexpected host exits use a shared startup
+cooldown, from 100 ms up to 30 seconds. A sustained healthy period of 60 seconds
+resets the circuit. Queued callers keep their original deadlines; no failed
+request, POST or Server Action is automatically replayed. Ordinary client
+cancellations and planned memory/idle retirements do not count as crashes.
+
+The private local data cache uses a versioned binary value transport when
+negotiated by the native worker launcher. Existing JSON clients remain accepted.
+Authentication, limits, leases, tag/path invalidation and cache policy are
+unchanged. This internal transport is not a public application API.
+
+## Production prerendering
+
+App and Pages static paths can render in separate Node processes during a
+production build. Path discovery runs once; results are published in a stable
+order. Small batches and `workers: 1` use the local renderer. Defaults account
+for available CPUs and memory. To set explicit ceilings:
+
+```js
+export default {
+  prerender: { workers: 4, maxMemoryMb: 2048 },
+};
+```
+
+`workers` accepts 1–8; `maxMemoryMb` accepts 256–16384 MiB and covers the sum of
+observed child-process RSS, including their rendering threads. This is a sampled
+admission budget, not an OS memory limit; it does not include the build
+coordinator. A path error or exhausted budget fails the build, stops pending
+work and closes the workers. Paths are not automatically retried: keep static
+data loaders free of mutations and independent of execution order.
+
+Build workers share a temporary, bounded cache for eligible App reads which the
+application explicitly elects to cache. It is discarded after the build and
+never uses the production cache. `no-store` requests and `Set-Cookie` responses
+are not coalesced. Authentication does not opt a read into caching; cached reads
+retain request-derived keys. Pages loaders retain their existing cache behavior.
+
+## Selected pages without browser JavaScript
+
+Use the PRNext-specific `htmlOnly` option for fully static, noninteractive App
+pages. Select registered route patterns exactly, or use a final `/**` subtree:
+
+```js
+export default {
+  htmlOnly: ['/about', '/articles/[slug]', '/manual/**'],
+};
+```
+
+Build validation requires Node App routes with complete static output. A
+dynamic pattern needs `dynamicParams = false` and a nonempty
+`generateStaticParams` result. Client Components, Server Actions, interactive
+`next/link`, scripts, ISR, PPR, `cacheComponents`, Edge and advanced parallel or
+intercepting routes are rejected for selected pages. Use ordinary `<a>` links.
+Unknown patterns fail the production build rather than silently doing nothing.
+
+HTML keeps CSS, fonts, metadata and resolved Suspense content. It has no
+bootstrap scripts or Flight payload; entering it performs document navigation.
+Unknown generated parameters return 404. The mode is enforced in production,
+including static export and standalone output; development retains its normal
+JavaScript tools. It is an explicit PRNext extension, not a Next.js config key.
+
+## Static browser output
+
+PRNext can serve a plain HTML/CSS/JavaScript directory:
+
+```sh
+prnext build ./my-site
+prnext start ./my-site --hostname 127.0.0.1 --port 3000
+```
+
+For output already produced by another builder, run that builder first, then
+select its **public browser directory** explicitly:
+
+```sh
+npm run build
+prnext build --adapter static --from dist --spa
+prnext output --json
+prnext start --hostname 127.0.0.1 --port 3000
+```
+
+Use `--spa` only when the browser router needs an `index.html` fallback. Omit it
+for a multipage site. `--adapter auto` can detect completed output; multiple
+candidates require `--from`. Importing output never executes the other builder.
+Vite browser builds, Astro static output, SvelteKit static output and Nuxt
+generated output can fit this model; their SSR servers and server API routes do
+not. Never point `--from` at a source/server directory or anything containing
+credentials. Static browser assets are public.
+
+`output: 'export'` in a supported React configuration is another build mode;
+it does not make request-time features such as private sessions or mutations
+available on a static file host. Test all required routes before choosing it.
+
+## Your infrastructure or PRNext Host
+
+PRNext is MIT-licensed and supports self-hosting. You can manage a production
+process with your existing infrastructure or the explicit `pstart`, `pstatus`,
+`plogs`, `prestart` and `pstop` commands; read `prnext pstart --help` first.
+`prnext host` is the local multi-application gateway command, distinct from the
+managed PRNext Host service. Process replacement does not roll back database
+changes or external effects. Avoid replacing a live service while testing docs.
+
+[PRNext Host](https://prnext.dev/host) offers an optional managed path, including
+deployment workflows linked to an AI assistant through MCP. Check current service
+availability and pricing there rather than promising an old rate or automatic
+access. Choose it when the user wants PRNext-managed hosting; self-hosting remains
+available.
+
+Where the connected Host deployment API supports this CLI, preview sources
+before any upload:
+
+```sh
+prnext deploy --dry-run
+```
+
+With deployment authorization and the intended account/server selected, the
+workflow is `prnext login`, `prnext deploy`, then `prnext update` for the linked
+project. Inspect each command's `--help`. CLI availability alone does not prove
+that a given Host server supports every candidate capability. Do not claim an
+upload or queued build is a live site; verify the returned deployment status
+and its actual URL.
+
+Cloud archives exclude standard credential/environment and generated paths, but
+review the dry run for project-specific sensitive files. Use remote project
+environment settings for secrets. `NEXT_PUBLIC_` variables and values deliberately
+placed in client code are public. Importing production environment variables is
+an explicit choice, not a reason to print credentials or copy `.env` into assets.
+
+## Observe before tuning
+
+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;
+a single pattern can still use all execution slots. Excess requests receive
+503 with `Retry-After`; an expensive request already executing is not preempted.
+This limits backlog monopolization, not all CPU use or application-level quotas.
+
+Use `prnext start --inspect` and `prnext inspect --json` for sampled route/cache
+and runtime observations. `prnext analyze --json` describes built browser
+JavaScript; it is not an SSR latency measurement. A production profile can be
+selected with `--profile balanced|speed|memory|classic`; benchmark the real
+workload before changing defaults. A benchmark from another machine or profile
+is not evidence for this application.

package/docs/ai/manifest.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "topics": [
+    { "id": "quickstart", "title": "Create and verify a project", "file": "docs/ai/quickstart.md" },
+    { "id": "routing", "title": "Routes and server/client boundaries", "file": "docs/ai/routing.md" },
+    { "id": "data", "title": "Data, caching and mutations", "file": "docs/ai/data.md" },
+    { "id": "compatibility", "title": "Next.js migration and supported behavior", "file": "docs/ai/compatibility.md" },
+    { "id": "deployment", "title": "Build and deploy", "file": "docs/ai/deployment.md" },
+    { "id": "troubleshooting", "title": "Diagnose and verify a fix", "file": "docs/ai/troubleshooting.md" }
+  ]
+}

package/docs/ai/quickstart.md

@@ -0,0 +1,171 @@
+# Quickstart
+
+[AI documentation index](../../AI.md)
+
+## Identify the installation
+
+Read `package.json`, the lockfile and the nearest project instructions. Use the
+installed version of this documentation. Keep an existing npm, pnpm or Yarn
+workspace instead of introducing a second manager or another lockfile.
+
+This package requires the exact peer family **React 19.3.1, React DOM 19.3.1 and
+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.
+
+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
+repository is a different workflow. Do not install a platform package separately
+or combine package versions to work around an installation failure.
+
+## Create a new application
+
+```sh
+npx @thomas.f/prnext create my-app
+cd my-app
+npm run dev
+```
+
+`create` writes a minimal App Router application and runs `npm install`. The
+default template uses TypeScript and includes the application components, CSS,
+scripts, TypeScript configuration and an `AGENTS.md` pointer to the installed
+PRNext documentation. It pins PRNext to the version running the command and the
+matching React peer versions.
+
+Use an empty directory or a new path. Quote paths containing spaces. Options:
+
+- `--js` creates JavaScript components without TypeScript configuration or type dependencies.
+- `--no-install` writes the files without installing dependencies; run `npm install` in the new application before starting it.
+- `--json` returns a structured creation report for automation.
+
+`npm i @thomas.f/prnext` only installs the package in the current project. It does
+not create application files, scripts or configuration. For an existing
+application, preserve its package manager and follow
+[Compatibility](compatibility.md) for a Next.js migration.
+
+## Set up an application manually
+
+To set up a new application manually, start with the manifest below, then install
+dependencies. For an existing application, merge only the necessary scripts and
+preserve its other fields.
+
+### `package.json`
+
+```json
+{
+  "name": "my-prnext-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "prnext dev",
+    "build": "prnext build",
+    "start": "prnext start",
+    "check": "prnext check",
+    "typecheck": "prnext typecheck"
+  }
+}
+```
+
+Install with the existing manager; for npm:
+
+```sh
+npm i --save-exact @thomas.f/prnext react@19.3.1 react-dom@19.3.1 react-server-dom-webpack@19.3.1
+npm i -D typescript @types/react@19 @types/react-dom@19 @types/node
+```
+
+`--save-exact` pins the resolved framework and React family in the manifest;
+commit the resulting lockfile as well. An unqualified PRNext install follows
+npm's `latest` tag. Use
+`@alpha` or a specific published version only when that is the intended release;
+do not assume a local source candidate exists on npm. If it installs another
+release, read that release's bundled documentation and peer requirements.
+
+Create the following TypeScript configuration only if the project has none.
+
+### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}
+```
+
+### `app/layout.tsx`
+
+```tsx
+import type { ReactNode } from 'react';
+
+export const metadata = {
+  title: 'My PRNext app',
+  description: 'A React application served with PRNext.',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return <html lang="en"><body>{children}</body></html>;
+}
+```
+
+### `app/page.tsx`
+
+```tsx
+export default function Home() {
+  return <main><h1>Hello from PRNext</h1></main>;
+}
+```
+
+Start development:
+
+```sh
+npx --no-install prnext check --json
+npm run dev
+```
+
+Use the URL printed by the server. Do not assume port 3000 is free or stop
+unrelated servers to obtain it. An explicit development port is supported:
+`npm run dev -- --port 3001`.
+
+No configuration file is required to build the two components. When needed, keep one
+`prnext.config.js|mjs|cjs|ts` or `next.config.js|mjs|cjs|ts`; multiple configuration
+files are rejected. For a new application using generated route declarations,
+`prnext.config.mjs` can contain:
+
+### `prnext.config.mjs`
+
+```js
+export default { typedRoutes: true };
+```
+
+## Validate each layer
+
+```sh
+npx --no-install prnext check --json
+npx --no-install prnext typegen --json
+npm run typecheck
+npm run build
+npm run start -- --hostname 127.0.0.1 --port 3001
+```
+
+`check` diagnoses configuration, routes, Node, native components and dependencies
+without compiling or installing. Project configuration is evaluated: run it only
+for trusted source. `typegen` and `typecheck` require TypeScript installed in the
+application and an existing tsconfig. They can update the selected tsconfig and
+`prnext-env.d.ts` to connect generated route declarations and missing Next-style
+type aliases, preserving existing/inherited settings. `typecheck` checks semantic
+errors even if `typescript.ignoreBuildErrors` is configured.
+
+A successful production build still needs request and browser verification.
+Test navigation, interaction, hydration and the application's important error
+paths. Keep `.prnext/`, `.prnext-types/`, `.prnext-dev/` and `.prnext-cache/` out
+of Git; keep the project's reviewed lockfile in Git. Do not delete generated
+directories while another process is using them.

package/docs/ai/routing.md

@@ -0,0 +1,214 @@
+# Routing and component boundaries
+
+[AI documentation index](../../AI.md)
+
+## Follow the application's router
+
+PRNext supports Next-style App and Pages conventions. Preserve the router the
+project already uses; installing PRNext does not require rewriting every page.
+Do not create both routers' implementations for the same URL.
+
+The App Router uses `app/` or `src/app/`, with convention files such as
+`page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx` and
+`route.ts`. A root layout returns `<html>` and `<body>`. App pages/layouts are
+Server Components unless a client boundary is declared. A route group such as
+`(marketing)` organizes files without adding a URL segment.
+
+The Pages Router uses `pages/` or `src/pages/`, including `index.tsx`, dynamic
+segments and `pages/api/`. Existing `getServerSideProps`, `getStaticProps` and
+`getStaticPaths` follow the Pages build/runtime pipeline. These hooks do not
+belong in an App Router page. Check a specific advanced routing feature against
+the installed implementation rather than assuming complete Next.js parity.
+
+App styles follow the page and its layout scopes instead of loading every
+page's stylesheet globally. Shared layout sheets are reused, and navigation
+loads the next page's sheets before committing its content. Keep shared global
+rules in the common layout and use CSS Modules for component-specific selectors.
+Do not rely on a sibling page's CSS being present. Loading/error/default and
+parallel-route branches can share a route's style plan; test their cascade as
+well as ordinary forward and back navigation in a production build.
+
+## Dynamic segments
+
+`app/products/[slug]/page.tsx` matches `/products/example`. App `params` and
+`searchParams` are asynchronous; await them. This complete page needs no database
+or network request:
+
+### `app/products/[slug]/page.tsx`
+
+```tsx
+export default async function Product({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<{ ref?: string | string[] }>;
+}) {
+  const { slug } = await params;
+  const { ref } = await searchParams;
+  return <main>
+    <h1>{slug}</h1>
+    <p>Reference: {Array.isArray(ref) ? ref.join(', ') : ref || 'none'}</p>
+  </main>;
+}
+```
+
+`[...slug]` is a required catch-all; `[[...slug]]` is optional. Catch-all values
+are arrays of path segments. Use `generateStaticParams()` only for values that
+can safely be produced at build time. Build-time prerendering can execute page
+code, so avoid mutations and unavailable request-dependent services there.
+
+## Isolate client interaction
+
+Keep a small client component for state and browser APIs.
+
+### `app/counter.tsx`
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+
+export default function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(value => value + 1)}>
+    Count: {count}
+  </button>;
+}
+```
+
+Import this component from a server page to render it. Do not turn the entire
+layout into a Client Component to fix one hook error. A client boundary includes
+its imported code: never import database clients, filesystem code or credentials
+through it. Pass appropriate serializable values across the boundary. A Server
+Action is an explicit supported server reference, not an ordinary callback prop.
+
+Client Components can participate in server rendering. Read `window`,
+`localStorage` and viewport-dependent state in a browser lifecycle such as
+`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.
+
+## Navigation and typed routes
+
+Existing application imports such as `next/link`, `next/navigation`,
+`next/headers` and `next/server` are adapted by the PRNext compiler for supported
+APIs. Scoped equivalents use `@thomas.f/prnext/link`, `/navigation`, `/headers`
+and `/server`. Do not globally replace working imports during a migration, and
+do not assume compiler aliases apply to an arbitrary external Node script.
+
+Use `Link` for in-app links and App `useRouter` from `next/navigation` inside a
+Client Component. Pages `useRouter` comes from `next/router`; they are different
+contracts. Server code can call `redirect()` or `notFound()` from
+`next/navigation`; let their control-flow exceptions reach the framework.
+
+Production link prefetching prioritizes keyboard focus, hover and touch over
+links entering the viewport. Both routers bound speculative work; an actual
+navigation takes priority. Data saver, offline/2G connections and hidden tabs
+disable speculation, while slower connections restrict it to intent. Browsers
+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.
+
+### Connection loss during App navigation
+
+App navigation retries transport failures of its GET request within a 30-second
+budget and at most three attempts. While disconnected, the current page and its
+mounted state remain visible. A newer navigation cancels the older attempt.
+Reconnection issues a fresh request with the current cookies; it does not serve
+a saved private response. Application errors and deployment mismatches retain
+their existing handling. Speculative prefetches are not queued offline.
+
+For an optional application-owned connection indicator:
+
+```tsx
+'use client';
+import { useOffline } from '@thomas.f/prnext/offline';
+
+export default function ConnectionStatus() {
+  const offline = useOffline();
+  return offline ? <p role="status">Waiting for a connection…</p> : null;
+}
+```
+
+The hook reports browser offline status and pending navigation recovery, not a
+guarantee that a server is reachable. Exhausted network recovery preserves the
+page and dispatches `prnext:navigation-error` on `window`, with `detail.message`
+for an application-owned retry notice. This recovery applies to App navigation;
+it does not add offline Pages routing, a service worker or persistent storage.
+
+Server Actions and other POSTs are **never automatically replayed**. If a mutation
+loses its response, it may already have run: keep the user's input and verify its
+result before offering an explicit retry. A full reload still loses ordinary
+in-memory state; persist drafts deliberately if they must survive reloads.
+
+With `typedRoutes: true`, `prnext typegen` writes a discovered route registry.
+For the dynamic page above, this materializes an encoded URL:
+
+### `lib/product-url.ts`
+
+```ts
+import { route } from '@thomas.f/prnext';
+
+export const productUrl = route('/products/[slug]', { slug: 'blue mug' });
+// /products/blue%20mug
+```
+
+Pass catch-all parameters as arrays. The helper rejects missing/unknown
+parameters, separators and dot segments. Add query strings through
+`URLSearchParams`; do not embed query or fragment syntax in the route pattern.
+Generated route checking is PRNext's registry, not the Next.js language-service
+plugin.
+
+## Retained App pages
+
+App layout branches retain inactive UI through React Activity. Effects stop
+while hidden, and returning to an authorized destination restores its mounted
+form state. The shared default budget is four inactive branches for two minutes,
+not four at every nesting level. It is an entry/time limit, not a byte-level RAM
+guarantee. It applies within a mounted layout; a new root layout loads a document.
+
+```js
+export default {
+  navigationCache: { maxEntries: 3, ttlMs: 60000, authCookies: ['session'] },
+};
+```
+
+Use `navigationCache: false` to disable retention. Server Actions, `router.refresh()`
+and observed cookie/authorization changes discard inactive branches while keeping
+the current page's client state. Back/forward navigation requests fresh Flight
+before revealing a retained destination. Cache hits do not bypass authorization.
+After a custom authentication request outside Server Actions, call
+`router.refresh()`. A browser integration may also dispatch
+`window.dispatchEvent(new Event('prnext:invalidate-navigation'))` to refresh and
+clear retained/prefetched state. This is in-memory UI retention, not offline
+storage or mutation replay.
+
+By default, cookie changes invalidate inactive branches while ordinary refresh
+keeps the active component state. Set `authCookies` to the application's actual
+session cookie names to also reset active branches when those credentials change.
+Unrelated preference cookies then do not affect retention. Authorization headers
+remain part of the identity. Identity is checked in each branch's authorized
+request context, including restored parallel slots. In development, the private
+identity key remains stable across Fast Refresh; build-time action-key rotation
+does not discard the active editor state.
+
+## Route Handlers
+
+An App Route Handler exports HTTP methods and returns a Web `Response` or
+`NextResponse`.
+
+### `app/api/health/route.ts`
+
+```ts
+export function GET() {
+  return Response.json({ ok: true });
+}
+```
+
+Read a body with `await request.json()` or `await request.formData()` in a
+handler that accepts `request: Request`. Validate its shape and authorize access
+before writing data. An App Route Handler is not a Pages `(req, res)` API handler.
+The example uses the default Node runtime; do not opt into Edge without checking
+all dependencies and the installed Edge restrictions.