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

package/docs/ai/data.md

@@ -114,13 +114,173 @@ enable them to silence a request-context error or assume their complete upstream
 behavior. Keep a working `unstable_cache` or fetch solution unless the project
 needs a different model.
 
+## Navigation stages
+
+Enable `cacheComponents: true` and `partialPrefetching: true` to separate runtime
+App Shell work from per-link prefetch work and actual navigation work:
+
+```jsx
+import { Suspense } from 'react';
+import { navigation, prefetch } from 'next/cache';
+
+async function Recommendations() {
+  await prefetch();
+  return <div>{await getCachedRecommendations()}</div>;
+}
+
+async function ExpensiveReport() {
+  await navigation();
+  return <div>{await getCachedReport()}</div>;
+}
+
+export default function Page() {
+  return <>
+    <Suspense fallback={<p>Loading recommendations</p>}><Recommendations /></Suspense>
+    <Suspense fallback={<p>Loading report</p>}><ExpensiveReport /></Suspense>
+  </>;
+}
+```
+
+Define and authorize the application-specific data functions above. Call gates
+before invoking a cached function, never inside its cached scope. Both gates
+require Cache Components. Static prerenders continue through them, so static
+output can already contain the result. Without partial prefetching, `prefetch()`
+has no effect and an explicit `Link prefetch={true}` requests the full route.
+
+A default Link requests the shell. `prefetch={true}` permits per-link work;
+content below `navigation()` waits for the navigation. Runtime previews are
+private, size-bounded and tied to the request's authorization identity. They do
+not authorize a subsequent navigation.
+Uncached runtime fetches and `connection()` remain deferred during speculative
+rendering. Put reusable I/O in a cached function to make it eligible for an
+earlier stage; a gate does not itself cache data.
+
+Pages and layouts may export `ensureStatic = 'shell'`, `'prefetch'` or
+`'navigation'`. Earlier stages are included in stricter levels. A descendant
+cannot weaken a parent; `false` conflicts with a static requirement elsewhere
+in the route. `'auto'` adds no requirement. Client Component exports are rejected.
+`'shell'` and `'prefetch'` request static output for those stages without adding
+a separate full-route build check. `'navigation'` validates complete static
+server output during build and development, including request APIs beneath
+Suspense, metadata and complete dynamic parameter sets. It requires nonempty,
+complete `generateStaticParams()` results for dynamic routes. All levels require
+Cache Components; shell/prefetch levels need partial prefetching to select stages.
+
+## Shared Redis Cache Components
+
+The optional first-party Redis handler shares `'use cache'` results across Node
+processes. Install `@redis/client@^6.3.0` only in applications using it; a normal PRNext
+installation and generated project do not require Redis.
+
+### `redis-handler.mjs`
+
+```js
+import { createRedisCache } from '@thomas.f/prnext/cache/redis';
+
+export default createRedisCache({
+  namespace: 'my-app-production-v1',
+  urlEnv: 'REDIS_URL',
+});
+```
+
+### `prnext.config.mjs`
+
+```js
+export default {
+  cacheComponents: true,
+  cacheHandlers: { remote: './redis-handler.mjs' },
+};
+```
+
+### `app/catalog/read.ts`
+
+```ts
+import { cacheLife, cacheTag } from 'next/cache';
+
+export async function readCatalog() {
+  'use cache: remote';
+  cacheLife('hours');
+  cacheTag('catalog');
+  return [{ id: 'demo', name: 'Demo product' }];
+}
+```
+
+Set the Redis URL in the server's runtime environment. It is not embedded in the
+handler bundle. Replicas sharing results need the same namespace and compatible
+build output. Use separate namespaces for unrelated apps, environments and
+incompatible deployments. This factory handles Cache Components. The separate
+incremental factory below handles native HTML/ISR, fetch and `unstable_cache`.
+
+Cache fills use a bounded cross-process lease. Atomic tag generations prevent a
+fill invalidated while running, or an expired lease owner, from publishing old
+data. Soft tag invalidation retains stale-while-revalidate behavior; immediate
+expiration prevents another replica from reading the old entry. Losing the tag
+registry invalidates existing entries rather than resurrecting them.
+
+Values are limited to 2 MiB, metadata to 64 KiB and each entry to 256 tags.
+The tag registry is bounded; excess cardinality conservatively invalidates the
+namespace. Default retention is at most seven days. Defaults use a 30-second
+lease, a 2.5-second fill wait and one-second command timeout. Reads can fall back
+to fresh computation on cache failure; invalidation failures remain errors.
+Cached callbacks must be safe to execute more than once after timeout or outage:
+leases reduce duplicate work, not provide exactly-once business operations.
+
+An already connected node-redis client can be supplied as `client`; its lifecycle
+remains the application's responsibility. Otherwise the handler connects lazily
+and owns its client. Use Redis appropriate for the application's availability,
+access controls and data sensitivity; a shared cache is not an authorization
+boundary or a durable database.
+
+## Shared Redis pages and request data
+
+Configure `cacheHandler` with the constructor returned by the incremental factory:
+
+```js
+// incremental-redis.mjs
+import { createRedisIncrementalCache } from '@thomas.f/prnext/cache/redis';
+export default createRedisIncrementalCache({ namespace: 'my-app-production' });
+```
+
+```js
+// prnext.config.mjs
+export default {
+  cacheHandler: './incremental-redis.mjs',
+  cacheMaxMemorySize: 0,
+};
+```
+
+Set `REDIS_URL` at runtime and install the optional `@redis/client@^6.3.0` client.
+The same configuration works for App and Pages HTML/ISR, static Route Handlers,
+cacheable `fetch` and `unstable_cache`. It does not cache private dynamic pages.
+Replicas must use compatible builds and share an application-specific namespace.
+Cache Components still select their own `cacheHandlers`; both factories may use
+the same namespace to share tag invalidations.
+
+The runtime acquires a shared generation lease before rendering, checks for a
+winner's result after waiting and carries that lease through publication. An
+invalidation or expired lease rejects late writes atomically. Runtime reads and
+publication remain bounded; unavailable Redis can prevent a page regeneration
+from succeeding. A shared cache is not a durable database or an exactly-once
+execution mechanism. Keep producers safe to retry.
+
+Incremental entries preserve Buffer and Map values, have a 16 MiB serialized
+limit and use V8-major-specific keys. The default generation lease is 60 seconds;
+`leaseMs` can be configured up to 120 seconds. Configure it for the expected
+generation duration. The default maximum storage age remains seven days.
+New cacheHandler builds include a native generation-lease capability check;
+use the matching PRNext native binary and rebuild existing output.
+
 ## Background work and durable data
 
-`after()` from `next/server` is supported in Node Route Handlers and Server
-Actions. It runs tracked callbacks after the response completes or disconnects;
-it is not supported for Server Components or Edge lifecycles. Cookie reads are
-allowed in that retained context, but cookie writes and path/tag invalidation
-are rejected there. Invalidate before returning from the mutation.
+`after()` from `next/server` is supported in Node Server Components (including
+layouts and metadata), Route Handlers and Server Actions. It runs tracked
+callbacks after the response completes or disconnects; static renders execute
+them during the build. Edge lifecycles remain unsupported. In a Server Component,
+read request data before registering the callback and capture the needed values:
+`headers()`, `cookies()` and `draftMode()` inside that callback are rejected.
+Route Handler and Action callbacks can read their retained request context.
+Cookie writes and path/tag invalidation are rejected after the response;
+invalidate before returning from the mutation.
 
 Tracked callbacks are bounded by the route's `maxDuration` and shutdown
 deadlines; forced termination can interrupt them. Use an external durable queue

package/docs/ai/deployment.md

@@ -20,6 +20,22 @@ 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
@@ -35,6 +51,141 @@ 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:
@@ -103,6 +254,13 @@ 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

package/docs/ai/quickstart.md

@@ -19,11 +19,36 @@ dependencies enabled. Consumers do not need Rust; building PRNext from its sourc
 repository is a different workflow. Do not install a platform package separately
 or combine package versions to work around an installation failure.
 
-## Minimal App Router application
+## Create a new application
 
-For a new application, start with the manifest below, then install dependencies.
-For an existing application, merge only the necessary scripts and preserve its
-other fields. Follow [Compatibility](compatibility.md) for a Next.js migration.
+```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`
 

package/docs/ai/routing.md

@@ -20,6 +20,14 @@ segments and `pages/api/`. Existing `getServerSideProps`, `getStaticProps` and
 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
@@ -94,6 +102,47 @@ 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:
 
@@ -112,6 +161,39 @@ parameters, separators and dot segments. Add query strings through
 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

package/docs/ai/troubleshooting.md

@@ -59,6 +59,13 @@ config/environment, custom Document or incompatible module changes can reload
 the document. Production prerendering and compression are not development HMR.
 An unused route need not rebuild until requested.
 
+Middleware and rewrites can select a cold destination after routing. PRNext
+compiles that destination through its private development compiler and continues
+the same request. It does not send an upload or action through middleware again.
+Retained parallel branches are compiled together when their source is needed.
+An error in an unrelated unopened route should not force that route into the
+active graph. Safe mode remains available for full-graph comparisons.
+
 For a controlled diagnosis, stop only the development process you own and try:
 
 ```sh
@@ -66,12 +73,26 @@ prnext dev --safe
 ```
 
 Safe mode uses full builds and fresh workers. `PRNEXT_BUILD_CACHE=0` disables
-PRNext's compiler/build caches when set in the current process environment; use
+PRNext's persistent compiler/build caches when set in the current process environment; use
 the syntax appropriate to the user's shell and restore the previous setting
-after the comparison. Optional cache-storage failures should fall back to work,
+after the comparison. In-memory compiler/transform reuse is a separate layer.
+Optional cache-storage failures should fall back to work,
 while genuine loader errors remain build failures. Do not delete every cache or
 lockfile as a first response, especially with another server running.
 
+Production builds can reuse eligible compiled JavaScript graphs and CSS Module
+outputs from the default CSS engine across processes through the private
+`.prnext-cache` directory. The successful artifact's `compilation-cache-report.json` and the
+programmatic build result's `compilationCache` report actual hits, misses and
+bypasses. These are compilation diagnostics, not response-cache or latency
+measurements. App graphs that discover actions or client boundaries, development
+graphs, the explicit PostCSS engine and custom loader/PostCSS pipelines still
+execute their compiler work.
+HTML, Flight responses and private rendered data are not stored in this cache.
+Changes to tracked dependencies, resolution candidates, options, environment
+or framework identity invalidate eligible entries. Corrupt or unavailable cache
+records fall back to compilation; `PRNEXT_BUILD_CACHE=0` disables their persistent reuse.
+
 For production observations:
 
 ```sh
@@ -85,6 +106,20 @@ exclude the full streaming body, and missing/dropped samples are not zero.
 `prnext analyze`, after building, rather than interpreting request time as
 compiler performance.
 
+Initial-JS analysis includes required hydration imports and SSR-used dynamic
+chunks. Schema 2 reports per-prerendered-path samples and the maximum size for
+each compression metric; a route's file list can be the union of its samples.
+Request-dependent or incomplete graphs are lower bounds. Their size budgets
+fail as `initial-unknown`, even if that lower bound is small. Do not present it
+as a complete measurement or a size saving. Rebuild old schema-1 baselines before
+comparing them with schema 2. An opaque webpack graph is also marked incomplete.
+
+For memoization questions, run `prnext compiler --json` after a successful build
+with `reactCompiler` enabled. Inspect the affected function and its skip reason,
+the reported graph coverage and cached-transform counts. An absent function in
+an observed-transforms report is not proof that it was optimized or rejected.
+Keep application behavior and hydration checks alongside this diagnostic.
+
 ## Connect the existing development MCP
 
 Start `prnext dev` in the application, then configure a compatible assistant to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thomas.f/prnext",
-  "version": "0.1.17-alpha",
+  "version": "0.1.18-alpha",
   "license": "MIT",
   "description": "Experimental Rust-powered runtime for Next.js apps, React and npm",
   "homepage": "https://prnext.dev",
@@ -115,6 +115,14 @@
     "./headers": "./compat/headers.cjs",
     "./server": "./compat/server.cjs",
     "./cache": "./compat/cache.cjs",
+    "./cache/redis": {
+      "types": "./compat/redis-cache.d.cts",
+      "default": "./compat/redis-cache.cjs"
+    },
+    "./offline": {
+      "types": "./compat/offline.d.cts",
+      "default": "./compat/offline.cjs"
+    },
     "./constants": "./compat/constants.cjs"
   },
   "dependencies": {
@@ -124,13 +132,17 @@
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
     "@edge-runtime/vm": "5.0.0",
+    "@jridgewell/trace-mapping": "0.3.31",
     "@vercel/nft": "1.11.0",
+    "babel-plugin-react-compiler": "1.0.0",
     "browserslist": "4.29.0",
     "dotenv": "16.6.1",
     "dotenv-expand": "11.0.7",
     "esbuild": "^0.28.2",
     "fontkit": "2.0.4",
+    "get-tsconfig": "4.14.3",
     "html-to-image": "1.11.13",
+    "jsonc-parser": "3.3.1",
     "lightningcss": "1.31.0",
     "loader-runner": "4.3.2",
     "oxc-parser": "0.155.0",
@@ -139,23 +151,30 @@
     "postcss": "8.5.28",
     "postcss-flexbugs-fixes": "5.0.2",
     "postcss-preset-env": "11.5.3",
+    "postcss-selector-parser": "7.1.6",
     "postcss-value-parser": "4.2.0",
     "react-refresh": "0.19.0",
     "schema-utils": "4.3.3",
     "webpack": "5.111.1"
   },
   "peerDependencies": {
+    "@redis/client": "^6.3.0",
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "react-server-dom-webpack": "19.3.1"
   },
+  "peerDependenciesMeta": {
+    "@redis/client": {
+      "optional": true
+    }
+  },
   "optionalDependencies": {
-    "@thomas.f/prnext-win32-arm64-msvc": "0.1.17-alpha",
-    "@thomas.f/prnext-win32-x64-msvc": "0.1.17-alpha",
-    "prnext-darwin-arm64": "0.1.17-alpha",
-    "prnext-darwin-x64": "0.1.17-alpha",
-    "prnext-linux-arm64-gnu": "0.1.17-alpha",
-    "prnext-linux-x64-gnu": "0.1.17-alpha"
+    "prnext-darwin-arm64": "0.1.18-alpha",
+    "prnext-darwin-x64": "0.1.18-alpha",
+    "prnext-linux-arm64-gnu": "0.1.18-alpha",
+    "prnext-linux-x64-gnu": "0.1.18-alpha",
+    "@thomas.f/prnext-win32-x64-msvc": "0.1.18-alpha",
+    "@thomas.f/prnext-win32-arm64-msvc": "0.1.18-alpha"
   },
   "engines": {
     "node": "^22.23.4 || ^24.22.1 || >=26.12.1"