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

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

@@ -2,6 +2,70 @@
 
 [AI documentation index](../../AI.md)
 
+## Compile large client imports only when used in development
+
+For App Router applications, the explicit experimental option below keeps
+literal client `import()` targets outside the initial browser graph. It defers
+their transformation and compilation, rather than only downloading an already
+compiled chunk later.
+
+```js
+// prnext.config.mjs
+export default {
+  experimental: { lazyDynamicImports: true }
+};
+```
+
+The option affects `prnext dev` only. Production keeps its ordinary dynamic
+chunks and does not use a development compilation endpoint. SSR also keeps its
+normal behavior. A `next/dynamic` component with `{ ssr: false }` is a useful
+candidate for an editor or other large browser-only feature; an import needed
+by SSR still needs its server compilation.
+
+On first use, the development server compiles the requested subgraph, publishes
+its immutable assets, and loads its CSS before resolving the import. Already
+loaded ESM dependencies are reused through their original module URLs, keeping
+shared objects and live bindings. Once activated, the module participates in
+subsequent JavaScript and stylesheet updates. A failed compilation can be
+requested again after correcting its source.
+
+Activated styles remain loaded for the generation, including when parallel
+slots select their own styles. Prefer CSS Modules or selectors scoped to the
+deferred feature when its global styles should not affect other components.
+
+The initial scope is App Router applications using the native compiler, with
+same-origin assets and no webpack hook or custom loaders. Literal imports from
+project `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts` and `.tsx` sources are eligible;
+computed imports, import attributes, literal requests containing `?` or `#`,
+imports inside installed packages and typed `.mts`/`.cts` helpers keep the
+ordinary compiler behavior. The compiler keeps the distinct module identities
+of those literal query and fragment imports. If an alias or a transitive
+dependency introduces a resolved query or fragment suffix inside a deferred
+graph, activation returns an explicit error
+before reusing any shared export bridge. Disable the option for that graph;
+query and fragment identities in deferred graphs are not currently supported.
+The compiler does not silently duplicate a shared CommonJS dependency: that
+case returns an explicit error. Convert that shared dependency to ESM or disable
+the option.
+Server Actions first introduced only by a deferred graph also require a static
+import or the ordinary compiler, because the running server implementation
+cannot be extended by publishing browser assets alone.
+
+There are at most 128 registered imports and 4,096 static JavaScript dependency
+identities per generation. Deferred assets have a cumulative 128 MiB budget per
+active generation. Existing development request and generation limits still
+apply. Public requests contain opaque registered IDs, never source filenames;
+an unknown ID cannot initiate a deferred compilation. Static ESM export bridges
+have their own startup cost, so measure your application's initial build and
+first-use delay before keeping the option enabled.
+
+Deferred JSON imports share their native ESM namespace and default object across
+importers. Deferred assets are written outside the served directory and published
+as complete immutable files. This experimental path requires hardlinks within
+the development generation's filesystem; disable `lazyDynamicImports` if that
+filesystem cannot create them. A failed activation keeps existing assets intact
+and conservatively accounts for any publication whose outcome is uncertain.
+
 ## Collect a useful failure
 
 Read the installed version, command, working directory, Node version, manager,
@@ -54,11 +118,33 @@ repair. Verify the interactive result after the change.
 
 ## HMR and cache failures
 
+When an Action overlaps a refresh or navigation, its mutation result remains
+independent from whether its older render is applied. A newer interaction can
+release a superseded development commit wait; it never replays the mutation.
+
+For a development state publication failure, keep the private
+`.prnext-dev/<session>/diagnostics/state-publication.json` receipt. It records the
+operation phase, error code, bounded rename attempts and last published sequence,
+without source contents or a full source path. Windows transient rename failures
+are retried for up to two seconds; a permanent failure preserves the previous
+complete state file. After a replacement runtime has activated, publication
+failure still retires obsolete runtimes through the gateway and keeps the
+existing three-generation snapshot bound. In-flight requests drain before
+their old runtime closes. Record the actual code and phase instead of assuming
+an antivirus or file watcher caused the lock.
+
 Development compiles requested routes and preserves state for compatible edits;
 config/environment, custom Document or incompatible module changes can reload
 the document. Production prerendering and compression are not development HMR.
 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 +152,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 +185,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.19-alpha",
   "license": "MIT",
   "description": "Experimental Rust-powered runtime for Next.js apps, React and npm",
   "homepage": "https://prnext.dev",
@@ -41,7 +41,8 @@
     "runtime/",
     "compat/",
     "native/",
-    "release/"
+    "release/",
+    "vendor/"
   ],
   "scripts": {
     "prepublishOnly": "node release/verify.mjs"
@@ -115,6 +116,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,38 +133,60 @@
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
     "@edge-runtime/vm": "5.0.0",
-    "@vercel/nft": "1.11.0",
+    "@jridgewell/trace-mapping": "0.3.31",
+    "@mapbox/node-pre-gyp": "2.0.3",
+    "@rollup/pluginutils": "5.4.0",
+    "acorn": "8.18.0",
+    "acorn-import-attributes": "1.9.5",
+    "async-sema": "3.1.1",
+    "babel-plugin-react-compiler": "1.0.0",
+    "bindings": "1.5.0",
     "browserslist": "4.29.0",
     "dotenv": "16.6.1",
     "dotenv-expand": "11.0.7",
     "esbuild": "^0.28.2",
+    "estree-walker": "2.0.2",
     "fontkit": "2.0.4",
+    "get-tsconfig": "4.14.3",
+    "glob": "14.0.2",
+    "graceful-fs": "4.2.11",
     "html-to-image": "1.11.13",
+    "jsonc-parser": "3.3.1",
     "lightningcss": "1.31.0",
     "loader-runner": "4.3.2",
+    "minimatch": "11.0.1",
+    "node-gyp-build": "4.8.4",
     "oxc-parser": "0.155.0",
     "path-to-regexp": "6.3.0",
     "picomatch": "4.0.7",
     "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",
+    "resolve-from": "5.0.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.19-alpha",
+    "prnext-darwin-x64": "0.1.19-alpha",
+    "prnext-linux-arm64-gnu": "0.1.19-alpha",
+    "prnext-linux-x64-gnu": "0.1.19-alpha",
+    "@thomas.f/prnext-win32-x64-msvc": "0.1.19-alpha",
+    "@thomas.f/prnext-win32-arm64-msvc": "0.1.19-alpha"
   },
   "engines": {
     "node": "^22.23.4 || ^24.22.1 || >=26.12.1"

package/runtime/action-client.mjs

@@ -1,19 +1,25 @@
-let referenceFactory;
-let transport;
+// A newly opened route can move this helper into a different development ESM
+// chunk. Its action proxies still belong to the already mounted application.
+// Production keeps the ordinary per-graph module state.
+const state = process.env.NODE_ENV === 'development'
+  ? globalThis[Symbol.for('prnext.development.server-actions')] ||= {}
+  : {};
 
 // App bootstrap installs the official Flight client after its module loader is
 // ready. Action proxy modules load through that same client graph afterwards.
 export function configureServerActions({ createServerReference, callServer }) {
-  referenceFactory = createServerReference;
-  transport = callServer;
+  state.referenceFactory = createServerReference;
+  state.transport = callServer;
 }
 
 export function callServer(id, args) {
+  const transport = state.transport;
   if (!transport) return Promise.reject(new Error('The PRNext Server Action transport is not initialized'));
   return transport(id, args);
 }
 
 export function createServerReference(id) {
+  const referenceFactory = state.referenceFactory;
   if (!referenceFactory) throw new Error('Server Action references must load after the PRNext Flight client');
   return referenceFactory(id, callServer);
 }

package/runtime/action-server.mjs

@@ -1,3 +1,4 @@
+import {reportRequestError} from './instrumentation.mjs';
 import { decodeReply, decodeAction, decodeFormState, createTemporaryReferenceSet } from 'react-server-dom-webpack/server.node';
 import { pathToFileURL } from 'node:url';
 import path from 'node:path';
@@ -126,6 +127,7 @@ export async function invokeAction(request) {
       } else if (navigation?.status === 404) {
         actionNotFound = true;
       } else {
+        reportRequestError(error,{routeType:'action'});
         console.error('[prnext]', error?.stack || error);
         actionError = errorPayload(error, request.production);
         failure = { message: error?.message || String(error), stack: error?.stack, digest: error?.digest };