@fluojs/react 0.1.0 → 0.2.0

package/README.md

@@ -4,19 +4,31 @@
 
 Runtime-neutral React integration for fluo applications.
 
+Preparing for the coordinated Node 24 release? Follow the [consumer migration guide](../../docs/getting-started/migrate-node24.md) before upgrading packages. React remains a `0.x` minor release, not a `1.0` graduation.
+
 ## Table of Contents
 
 - [Installation](#installation)
 - [When to Use](#when-to-use)
+- [Zero-to-First-Page Workflow](#zero-to-first-page-workflow)
 - [Stable SSR Mental Model](#stable-ssr-mental-model)
+- [React User Concept Translation](#react-user-concept-translation)
 - [Runtime and Peer Contract](#runtime-and-peer-contract)
 - [Phase Boundaries](#phase-boundaries)
 - [ReactModule Registration](#reactmodule-registration)
+- [Application Page Renderer](#application-page-renderer)
+- [Render Policy Decorators](#render-policy-decorators)
+- [SSR Diagnostic Phases](#ssr-diagnostic-phases)
+- [HTTP Error Documents](#http-error-documents)
 - [Router and Path Decorators](#router-and-path-decorators)
+- [Bootstrap-Resolved Page Catalog](#bootstrap-resolved-page-catalog)
+- [Path-Only Page Type Generation](#path-only-page-type-generation)
+- [Consumer Testing Loop](#consumer-testing-loop)
 - [Web Streams SSR](#web-streams-ssr)
 - [Hydration Asset Contract](#hydration-asset-contract)
 - [Vite Asset Manifest Integration](#vite-asset-manifest-integration)
 - [Client Navigation Runtime](#client-navigation-runtime)
+- [Native Form Mutations](#native-form-mutations)
 - [Experimental RSC Prototype](#experimental-rsc-prototype)
 - [Experimental Server Functions](#experimental-server-functions)
 - [RSC Graduation Policy](#rsc-graduation-policy)
@@ -27,9 +39,9 @@ Runtime-neutral React integration for fluo applications.
 
 ## Installation
 
-The first public release target for this package is `0.1.0`. The manifest starts at
-`0.0.0` so Changesets can publish the initial `0.1.0` version through the canonical
-release workflow.
+The package has completed its initial `0.1.0` release and no longer uses the `0.0.0` bootstrap
+placeholder. Future versions are recorded through committed Changesets and published only through
+the canonical release workflow.
 
 When the package is published, install it with React and React DOM as peers:
 
@@ -46,6 +58,36 @@ places React routers into ordinary module controller metadata, and `@Router(...)
 DTO binding, versioning, guards, interceptors, headers, route validation, matching, and dispatch
 continue to use the HTTP runtime contracts.
 
+## Zero-to-First-Page Workflow
+
+Use the official generated composition when you want streamed SSR, hydration, and Vite assets
+without assembling every stable seam before editing the first page:
+
+```bash
+fluo new my-react-app --starter react-vite-ssr
+cd my-react-app
+pnpm dev
+```
+
+Open `/products/sku-42?preview=true` and edit `src/page.tsx`. The explicit `@Router(...)` / `@Path(...)`
+handler remains in `src/app.ts` and returns `createElement(ProductPage)`, one `ReactElement`, so `@fluojs/http` still
+owns matching, DTO binding and validation, middleware, guards, interceptors, request scopes, and
+not-found behavior.
+
+The generated wiring moves the incidental first-edit work into discoverable application files:
+
+- `src/entry-server.tsx` owns the replaceable `ReactPageRenderer`, parses the application-loaded
+  manifest with `@fluojs/react/vite`, and returns `ReactServerEntry` with
+  `createReactServerEntry(...)`.
+- `src/react-app.tsx` gives server rendering and hydration one document,
+  `ReactClientRouterProvider`, route snapshot, and stylesheet composition.
+- `src/entry-client.tsx` hydrates that same tree, while `src/main.ts` and `src/load-manifest.ts` keep
+  filesystem loading and actionable build-output failures at the Node.js application boundary.
+
+Advanced applications can replace the generated renderer or pass explicit hydration options to
+`createReactServerEntry(...)`; the stable APIs below remain available. No runtime-neutral root export
+imports Node.js, Vite, or browser code, and the starter does not add another route matcher.
+
 ## Stable SSR Mental Model
 
 The stable `0.1.0` model is HTTP-first React SSR. `@Router(...)` and `@Path(...)` are lexical
@@ -58,8 +100,18 @@ validation, guards, interceptors, headers, module middleware, request scopes, an
 This package is therefore **not** a Next.js App Router clone, React Server Components framework,
 TanStack route tree, Angular `Routes[]` table, file-route scanner, or primary React-owned
 `routes: []` configuration model. Treat React routers as page-shaped HTTP handlers. Route discovery
-and dispatch stay in the existing fluo module/controller pipeline, and page handlers return either
-ordinary values or `createReactServerEntry(...)` when they want streamed HTML.
+and dispatch stay in the existing fluo module/controller pipeline. Page handlers may return ordinary
+HTTP values, return one valid `ReactElement` for the configured application page renderer, or return
+`createReactServerEntry(...)` explicitly when they need per-route SSR options.
+
+## React User Concept Translation
+
+If your starting vocabulary is pages, layouts, loaders, actions, navigation, pending UI, metadata,
+hydration, or build assets, use the concise
+[React concepts in fluo guide](../../docs/guides/react-user-concepts.md). It separates shipped
+equivalents, intentionally different behavior, experimental surfaces, and unsupported concepts,
+then follows one runnable path from `@Router(...)`/`@Path(...)` through the application renderer,
+Vite assets, hydration, client navigation, and a native form mutation.
 
 ## Runtime and Peer Contract
 
@@ -133,8 +185,276 @@ sources, so `createHandlerMapping(...)` and `Dispatcher` still detect duplicate
 module-level middleware, create request scopes, run guards and interceptors, and resolve route
 versioning.
 
+## Application Page Renderer
+
+Register one application-owned `renderPage` callback when every page should share the same document
+shell, providers, hydration assets, route snapshot wiring, and recoverable-render policy. The callback
+implements `ReactPageRenderer`, receives one `ReactElement` plus the active `ReactRenderContext`, and
+must return `ReactServerEntry`. `ReactModule.forRoot(...)` registers and exports it through
+`REACT_PAGE_RENDERER`, so routers can inject the callback without creating a second response path.
+
+```tsx
+import { Module } from '@fluojs/core';
+import {
+  Path,
+  ReactModule,
+  Router,
+  createReactServerEntry,
+  type ReactPageRenderer,
+  type ReactRenderContext,
+} from '@fluojs/react';
+import {
+  ReactClientRouterProvider,
+  createReactRouteSnapshot,
+} from '@fluojs/react/client';
+
+const hydrationOptions = {
+  assetMap: { 'client.js': '/assets/client.123.js' },
+  bootstrapModules: ['/assets/client.123.js'],
+} as const;
+
+const renderPage: ReactPageRenderer = (page, context) => {
+  const initialSnapshot = createReactRouteSnapshot({
+    params: context.request.params,
+    url: context.request.url,
+  });
+
+  return createReactServerEntry(
+    <html lang="en">
+      <body>
+        <ReactClientRouterProvider initialSnapshot={initialSnapshot}>
+          {page}
+        </ReactClientRouterProvider>
+      </body>
+    </html>,
+    hydrationOptions,
+  );
+};
+
+@Router('/products')
+class ProductRouter {
+  @Path('/:id')
+  show(_input: undefined, context: ReactRenderContext) {
+    return <main>Product {context.request.params.id}</main>;
+  }
+}
+
+@Module({
+  imports: [ReactModule.forRoot({ controllers: [ProductRouter], renderPage })],
+})
+class AppModule {}
+```
+
+The root package does not import `@fluojs/react/client` or `@fluojs/react/vite`. Applications may
+compose client helpers explicitly as above and may close over hydration options produced from an
+already-loaded manifest by `createReactViteAssetManifest(...)`. The renderer does not discover
+manifests, generate bundles, match routes, or bypass DTO binding, middleware, guards, interceptors,
+request scopes, abort propagation, shell failure handling, or recoverable streaming behavior.
+
+When `renderPage` is configured, the final value from an `@Path(...)` request is passed to that
+callback only when React `isValidElement(...)` recognizes it as one `ReactElement`. Plain objects,
+strings, arrays, `null`, and other ordinary values keep the normal HTTP response path. Explicit
+`ReactServerEntry` values remain unchanged and do not pass through the configured callback. The
+`REACT_PAGE_RENDERER` token remains available when another application provider needs to invoke the
+same renderer explicitly.
+
+Returning a `ReactElement` without configuring `renderPage` fails before response commit with
+`ReactSsrDiagnosticError`, code `react-ssr-missing-page-renderer`, and an actionable message. Configure
+`ReactModule.forRoot({ ..., renderPage })` or return `createReactServerEntry(...)` explicitly.
+
+## Render Policy Decorators
+
+Use `@PageLayout(...)`, `@SuspenseFallback(...)`, and `@PageMetadata(...)` when one React router
+class or `@Path(...)` method needs route-local composition while the application keeps one
+`renderPage` callback. Layout and fallback decorators accept component references, not pre-created
+JSX elements. `PageMetadata` accepts a synchronous request-aware factory. Their metadata is resolved
+after HTTP matching and passed only to the application page renderer; it never changes paths,
+matching precedence, params, errors, or not-found behavior.
+
+```tsx
+import { Suspense, createElement, type ReactElement } from 'react';
+import {
+  PageLayout,
+  PageMetadata,
+  Path,
+  ReactModule,
+  Router,
+  SuspenseFallback,
+  createReactPageMetadataElements,
+  createReactServerEntry,
+  resolveReactPageMetadata,
+  type ReactPageLayoutProps,
+  type ReactPageRenderer,
+  type ReactSuspenseFallbackProps,
+} from '@fluojs/react';
+
+function ShopLayout({ children, context }: ReactPageLayoutProps) {
+  return <section data-request-path={context.request.path}>{children}</section>;
+}
+
+function ProductFallback({ context }: ReactSuspenseFallbackProps) {
+  return <p>Loading {context.request.params.id}…</p>;
+}
+
+const renderPage: ReactPageRenderer = (page, context, policies) => {
+  const metadata = resolveReactPageMetadata(policies, context);
+  const pageBoundary = policies.suspenseFallback === undefined
+    ? page
+    : createElement(Suspense, {
+        fallback: createElement(policies.suspenseFallback, { context }),
+      }, page);
+  const composedPage = policies.layouts.reduceRight<ReactElement>(
+    (children, Layout) => createElement(Layout, { children, context }),
+    pageBoundary,
+  );
+
+  return createReactServerEntry(
+    <html lang="en">
+      <head>{createReactPageMetadataElements(metadata)}</head>
+      <body>{composedPage}</body>
+    </html>,
+  );
+};
+
+@PageLayout(ShopLayout)
+@Router('/products')
+class ProductRouter {
+  @PageMetadata(({ request }) => ({
+    meta: [{ content: `Product ${request.params.id}`, name: 'description' }],
+    title: `Product ${request.params.id}`,
+  }))
+  @SuspenseFallback(ProductFallback)
+  @Path('/:id')
+  show() {
+    return <ProductPage />;
+  }
+}
+
+ReactModule.forRoot({ controllers: [ProductRouter], renderPage });
+```
+
+Resolved layouts are ordered outermost to innermost: base class, derived class, base method, then
+derived method. Layouts compose across inheritance. The nearest fallback wins, so a method fallback
+overrides a class fallback and a derived declaration overrides a base declaration. A class or method
+site may declare each policy kind once; same-site duplicates fail during bootstrap.
+
+Metadata factories use the same broad-to-specific class and method order. The nearest defined title
+wins. Later `<meta>` descriptors replace earlier descriptors with the same `name` or `property`
+identity, and later `<link>` descriptors replace the same exact `rel` plus `href` pair. Unrelated
+descriptors preserve declaration order. `resolveReactPageMetadata(...)` returns a frozen bounded
+snapshot, and `createReactPageMetadataElements(...)` creates ordinary React title, meta, and link
+elements so React owns text and attribute escaping. Neither helper discovers Vite assets, creates
+script tags, accepts raw HTML, or serializes arbitrary inline data.
+
+`ReactRenderContext` includes the active request-scope `container`. Policy components receive that
+context as an explicit prop, but fluo does not instantiate React components through DI or resolve
+tokens on their behalf. A policy without `renderPage`, a class policy outside `@Router(...)`, or a
+method policy outside `@Path(...)` fails bootstrap with `ReactRenderPolicyConfigurationError` and a
+stable value from `REACT_RENDER_POLICY_DIAGNOSTIC_CODES`.
+
+Metadata factories receive `ReactPageMetadataContext`: the active `request`, optional `requestId`,
+and the same request-scope `container` identity as the handler and renderer. The context intentionally
+omits `response`, so metadata cannot change status, headers, or commit timing. fluo does not instantiate
+factories through DI or resolve tokens for them. Load asynchronous data through the matched HTTP
+handler before page composition; metadata factories remain synchronous.
+
+`@SuspenseFallback(...)` supplies an ordinary React Suspense fallback for descendants that suspend
+during SSR. It does not observe handler `await`, effects, event handlers, native form submission, or
+full-document/client navigation pending state. HTTP pipeline errors, not-found/404 responses,
+pre-commit shell failures, request aborts, and post-shell recoverable errors keep their separate
+existing phases. The complete ordering, inheritance, duplicate, and phase decision is recorded in
+the [React render policy decorator decision](../../docs/architecture/react-render-policy-decorators.md).
+The follow-up [React page render policy decision](../../docs/architecture/react-page-render-policies.md)
+accepts metadata but rejects a generic error-presentation decorator and page-local not-found
+presentation. HTTP pipeline failures, shell failures, post-shell recoverable errors, request aborts,
+client React errors, unmatched routes, and handler-thrown `NotFoundException` outcomes retain their
+existing owners. No placeholder error or not-found export is provided.
+
+## SSR Diagnostic Phases
+
+Register `onDiagnostic` on `ReactModule.forRoot(...)` when application logging or diagnostics tooling
+needs one stable event shape across HTTP and React rendering boundaries:
+
+```tsx
+ReactModule.forRoot({
+  controllers: [ProductRouter],
+  renderPage,
+  onDiagnostic(diagnostic) {
+    applicationDiagnostics.report(diagnostic);
+  },
+});
+```
+
+Each `ReactSsrDiagnostic` contains `code`, `phase`, the original `error`, the active `request`, and an
+optional `requestId`. The callback is observational: an exception thrown by it does not replace the
+request outcome. Stable phases and codes are:
+
+| Phase | Code | Boundary |
+| --- | --- | --- |
+| `http-pipeline` | `react-ssr-http-pipeline-failure` | DTO binding, middleware, guards, interceptors, handlers, and other failures before React shell rendering. |
+| `http-pipeline` | `react-ssr-missing-page-renderer` | A valid `ReactElement` reached an `@Path(...)` response without `renderPage` configuration. |
+| `pre-commit-shell` | `react-ssr-pre-commit-shell-failure` | React shell creation or buffered stream collection failed before response commit. The original thrown `Error` identity is preserved. |
+| `request-abort` | `react-ssr-request-abort` | The request signal or abort probe stopped React rendering; existing no-commit or committed-stream abort behavior remains unchanged. |
+| `post-shell-recoverable` | `react-ssr-post-shell-recoverable-error` | React reported a recoverable render error after a shell could be written; status and headers are not rewritten. |
+
+`REACT_SSR_DIAGNOSTIC_PHASES` and `REACT_SSR_DIAGNOSTIC_CODES` expose these values for comparisons.
+The existing `onRecoverableError` entry hook also receives `code` and `phase` in
+`ReactRecoverableErrorContext`.
+
+## HTTP Error Documents
+
+Use `createReactErrorRepresentationProvider(...)` when the application wants React to produce the
+optional HTML bytes selected by the HTTP error representation contract:
+
+```tsx
+import { bootstrapApplication } from '@fluojs/runtime';
+import {
+  createReactErrorRepresentationProvider,
+  createReactServerEntry,
+} from '@fluojs/react';
+
+const html = createReactErrorRepresentationProvider({
+  renderDocument({ json }) {
+    return createReactServerEntry(
+      <html lang="en">
+        <body><main>{json.error.status}: {json.error.message}</main></body>
+      </html>,
+    );
+  },
+});
+
+const app = await bootstrapApplication({
+  errorRepresentation: { html },
+  rootModule: AppModule,
+});
+```
+
+`@fluojs/http` performs route-miss conversion and `Accept` negotiation before this adapter runs.
+The callback receives `HttpErrorRepresentationContext`, including canonical JSON and the active
+request-scope container. It does not receive response mutation authority. The React entry is fully
+buffered before HTTP applies status, `Content-Type`, `Vary`, `HEAD` suppression, and commit.
+
+React escapes `json.error.message` in the example because it is a JSX text child. The application
+still owns the complete trusted-HTML document contract: do not move request-derived or error-derived
+content into `dangerouslySetInnerHTML` unless it has passed an application-approved sanitizer or
+equivalent trusted-content boundary.
+
+`ReactServerEntry.status` and `ReactServerEntry.headers` are ignored on this path. The helper never
+calls `ReactPageRenderer`, `PageLayout`, `PageMetadata`, `SuspenseFallback`, or the page catalog, and
+it never matches a URL. A render failure propagates to HTTP's one-shot canonical JSON fallback;
+matched-page pre-commit shell failures remain a separate React SSR diagnostic phase and do not invoke
+the provider. See the
+[HTTP error representation decision](../../docs/architecture/http-error-representations.md).
+
 ## Router and Path Decorators
 
+`@Path()` and `@Path(undefined)` use `''`, so `@Router('/cats')` serves GET `/cats`
+and `@Router()` serves GET `/`. An explicit `'/'` has the same effective route but a
+different raw path and never escapes the prefix. Omitted options leave the React metadata's
+`options` property absent; `Path(undefined, options)` still records explicit options.
+HTTP, React, and inspection metadata keep their existing contracts, including route conflicts
+and grammar rejection. `PageLayout`, `SuspenseFallback`, and `PageMetadata` still require values.
+
 `@Router(basePath)` marks a class as a React router and writes HTTP controller metadata equivalent
 to `@Controller(basePath)`. It also stores React router marker metadata readable through
 `getReactRouterMetadata(...)` for diagnostics and future rendering integration.
@@ -176,12 +496,155 @@ The [HTTP catch-all route grammar decision](../../docs/architecture/http-catch-a
 defers wildcard adoption. React does not add its own syntax: page handlers should keep explicit
 server routes, and any future catch-all must first become an approved `@fluojs/http` contract.
 
+## Bootstrap-Resolved Page Catalog
+
+Use `createReactPageCatalog(...)` after HTTP handler compilation when tooling needs a read-only list
+of React pages. Pass the authoritative `HandlerDescriptor[]` from `createHandlerMapping(...)` or
+`app.dispatcher.describeRoutes()`. The result contains only handlers marked by both `@Router(...)`
+and `@Path(...)`, in descriptor registration order.
+
+```ts
+import { createHandlerMapping } from '@fluojs/http';
+import { createReactPageCatalog } from '@fluojs/react';
+
+const mapping = createHandlerMapping([{ controllerToken: ProductRouter }]);
+const pages = createReactPageCatalog(mapping.descriptors);
+
+console.log(pages[0]);
+// {
+//   kind: 'react-page', method: 'GET', path: '/v2/products/:productId',
+//   version: '2', params: ['productId'], router: 'ProductRouter', handler: 'show'
+// }
+```
+
+`getReactRouterMetadata(...)` and `getReactPathMetadata(...)` expose static values authored at the
+decorator sites, such as the router base path, relative page path, and React options. The catalog is
+different: its method, path, version, params, module, router, and handler fields are projected from
+bootstrap-resolved HTTP descriptors, so controller composition and URI versioning are already
+reflected. The returned array, entries, and `params` arrays are frozen defensive snapshots.
+
+Catalog construction is observational only. It never calls or replaces the HTTP matcher and has no
+role in route conflict detection, request dispatch, not-found behavior, or non-React handlers. It
+does not create a route tree, client manifest, relative-route model, prefetch layer, or cache.
+
+## Path-Only Page Type Generation
+
+Use `fluo typegen` to bootstrap an application module, project its compiled React page catalog, and
+write application-owned TypeScript route helpers. The output comes from the dedicated
+`@fluojs/react/typegen` subpath; the runtime-neutral package root does not export the generator.
+
+```bash
+fluo typegen ./src/app.ts --output ./src/generated/react-pages.ts
+fluo typegen ./src/admin.ts --export AdminModule --output ./src/generated/admin-pages.ts
+fluo typegen ./src/app.ts --output ./src/generated/react-pages.ts --check
+fluo typegen ./src/app.ts --output ./src/generated/react-pages.ts --watch
+```
+
+The command creates the output directory when needed, overwrites stale output deterministically,
+and reports `CREATE`, `UPDATE`, or `UNCHANGED`. Atomic replacement prevents partial publication and
+byte-identical runs do not rewrite the file. `--check` compares exact generated bytes without writes
+and classifies a structurally corrupted current-version body as malformed rather than stale.
+`--watch` installs its application-module watcher before startup generation, reruns once for changes
+observed during that generation before reporting ready, and then serializes coalesced changes while
+preserving the last valid artifact after generation failures. Native `.js` and `.mjs` dependencies
+are evaluated from a current module graph for each generation. Every run closes its bootstrapped
+application after reading `app.dispatcher.describeRoutes()`. Import the generated artifact from
+application code:
+
+```ts
+import {
+  reactPageRoutes,
+  type ReactPageParams,
+  type ReactPagePath,
+  type ReactPageRouteId,
+} from './generated/react-pages.js';
+
+const productHref = reactPageRoutes['GET /products/:productId ProductRouter show'].href({
+  productId: 'desk/chair',
+});
+// /products/desk%2Fchair
+```
+
+Generated route ids use the stable catalog `id`. Static builders accept no parameters; dynamic
+builders require every catalog path parameter and encode each value with `encodeURIComponent(...)`.
+The artifact also exports `ReactPagePathById`, `ReactPageParamsById`, `ReactPagePath<RouteId>`,
+`ReactPageParams<RouteId>`, `ReactPageRoute`, `ReactPageLinkProps`, and `ReactPageNavigator`.
+
+Each generated route also binds the same href builder to declarative `Link` and programmatic
+`push`/`replace` authoring. `link(...)` returns an ordinary `{ href: string }` object for the existing
+real-anchor `Link`; `push(router, ...)` and `replace(router, ...)` resolve the same absolute href before
+calling the existing `ReactRouter` string overload. Route identity and exact params therefore remain
+visible at the callsite without a second runtime route table:
+
+```tsx
+import { Link, useRouter } from '@fluojs/react/client';
+import { reactPageRoutes } from './generated/react-pages.js';
+
+const productsRoute = reactPageRoutes['GET /products ProductRouter index'];
+const productRoute = reactPageRoutes['GET /products/:productId ProductRouter show'];
+
+function ProductNavigation({ productId }: { readonly productId: string }) {
+  const router = useRouter();
+
+  return (
+    <nav>
+      <Link {...productsRoute.link()}>Products</Link>
+      <Link {...productRoute.link({ productId })}>Current product</Link>
+      <button type="button" onClick={() => productRoute.push(router, { productId })}>Open</button>
+      <button type="button" onClick={() => productRoute.replace(router, { productId })}>Replace</button>
+    </nav>
+  );
+}
+```
+
+Static `link`, `push`, and `replace` methods accept no params; parameterized methods require every
+path param and reject missing or extra keys. The existing generated `href(...)` builders,
+`<Link href={stringOrUrl}>`, and `router.push(...)` / `router.replace(...)` string or `URL` calls remain
+supported. Generated methods only produce or pass absolute href strings into those existing APIs, so
+real-anchor fallback, full-document HTTP navigation, matching, DTO binding, guards, interceptors, and
+not-found behavior keep their current owners.
+
+This contract is deliberately path-only. It does not generate query strings, fragments, relative
+routes, optional parameters, or a client route tree. Typegen rejects every catalog entry with a
+`version` because the compiled catalog does not identify whether version selection came from the
+URI, a header, media type, or a custom strategy; emitting one absolute href would otherwise claim a
+URL contract that may be false.
+
+## Consumer Testing Loop
+
+Use existing React, HTTP, testing, TypeScript, and browser seams as one layered consumer loop. No
+React-specific testing helper is needed because the repeated setup is already isolated by ordinary
+fixtures and the real dispatcher remains the subject of request tests.
+
+1. **Render-policy units**: call pure policy and metadata helpers directly. Cover broad-to-specific
+   layout order, nearest fallback or metadata precedence, and configuration diagnostics without
+   bootstrapping a browser.
+2. **Request dispatch**: build the authored module with `createTestApp({ rootModule })`, request the
+   explicit `@Path(...)` route through `app.request(...).send()`, and close the app in `finally`.
+   Include a direct `ReactElement` return and the missing-renderer diagnostic so the real HTTP
+   dispatcher, request scope, response ownership, and application renderer stay covered.
+3. **Generated-route compilation**: generate from the bootstrapped `HandlerDescriptor` catalog, run
+   TypeScript over positive and negative consumer fixtures, and run `fluo typegen ... --check` in CI.
+   Positive fixtures use known route ids and complete params; negative fixtures cover unknown ids,
+   missing or extra params, and stale, malformed, missing, or unsupported-version artifacts.
+4. **Hydration**: render the same application component on the server and hydrate it with
+   `hydrateRoot(...)`. The positive fixture expects interaction with no diagnostics. A deliberately
+   mismatched fixture captures `onRecoverableError` so mismatch reporting itself cannot regress.
+5. **Production browser and progressive enhancement**: run Playwright against built assets, fail on
+   console/page errors, and use a separate `javaScriptEnabled: false` context to submit the native
+   form through the ordinary `POST` → `303` → `GET` flow.
+
+Executable references are `src/render-policy.test.ts`, `src/direct-page-return.test.ts`,
+`../cli/src/commands/typegen-navigation.test.ts`, `../../examples/react-vite-ssr/src/app.test.ts`,
+`../../examples/react-vite-ssr/src/hydration.test.ts`, and
+`../../examples/react-vite-ssr/tests/production-hydration.spec.ts`.
+
 ## Web Streams SSR
 
-Return `createReactServerEntry(...)` from a React page handler to stream HTML through the existing
-fluo HTTP dispatcher. Guards, interceptors, module middleware, route headers, `@HttpCode(...)`, DTO
-binding, request scopes, and duplicate route detection all run before `renderReactResponse(...)`
-finalizes the HTML response.
+Return one `ReactElement` through a configured application page renderer, or return
+`createReactServerEntry(...)` explicitly, to stream HTML through the existing fluo HTTP dispatcher.
+Guards, interceptors, module middleware, route headers, `@HttpCode(...)`, DTO binding, request scopes,
+and duplicate route detection all run before `renderReactResponse(...)` finalizes the HTML response.
 
 ```tsx
 import { HttpCode, RequestDto, FromPath } from '@fluojs/http';
@@ -216,6 +679,9 @@ when an adapter provides one, and throws shell render failures before response b
 Recoverable Suspense errors are reported through `onRecoverableError` and do not rewrite an already
 committed status. Call `renderReactResponse(entry, requestContext)` directly only when a custom
 handler needs to finalize the response itself instead of returning the entry to the dispatcher.
+On streaming hosts, an early response-sink close or a failed `write(...)` / `waitForDrain()` cancels
+the unfinished React reader exactly once and releases its lock. Sink failures remain the reported
+failure rather than being replaced by reader-cancellation cleanup.
 
 ## Hydration Asset Contract
 
@@ -415,6 +881,85 @@ matches an explicit `@Path(...)`/HTTP route or returns its normal not-found resp
 deployment-level document rewrite may be configured separately, but it does not create a React route
 grammar or change server DTO validation.
 
+## Native Form Mutations
+
+Use a native HTML form when a React page needs a mutation that remains functional before hydration or
+with client JavaScript disabled. Submit to an ordinary `@Post(...)` route rather than creating a
+React-owned action transport. The runnable `examples/react-vite-ssr/` slice uses
+`multipart/form-data`, which lets the browser provide the multipart boundary while the existing
+adapter and `@RequestDto(...)` body-binding path materialize the fields.
+
+```tsx
+function ProductForm({ name, sku }: { readonly name: string; readonly sku: string }) {
+  return (
+    <form action={`/products/${encodeURIComponent(sku)}`} encType="multipart/form-data" method="post">
+      <label htmlFor="product-name">Product name</label>
+      <input defaultValue={name} id="product-name" minLength={3} name="name" required />
+      <button type="submit">Save product</button>
+    </form>
+  );
+}
+```
+
+The target remains a normal HTTP handler. DTO binding and validation run once at the request
+boundary; module middleware, guards, interceptors, request-scoped providers, observers, and adapter
+response writing keep their ordinary ordering and ownership.
+
+```ts
+import {
+  FromBody,
+  FromPath,
+  Post,
+  RequestDto,
+  type RequestContext,
+  UseGuards,
+  UseInterceptors,
+} from '@fluojs/http';
+import { Router } from '@fluojs/react';
+import { IsString, MinLength } from '@fluojs/validation';
+
+class RenameProductRequest {
+  @MinLength(3, {
+    code: 'PRODUCT_NAME_TOO_SHORT',
+    message: 'Product name must contain at least 3 characters.',
+  })
+  @IsString()
+  @FromBody('name')
+  name = '';
+
+  @IsString()
+  @FromPath('sku')
+  sku = '';
+}
+
+@Router('/products')
+class ProductRouter {
+  @Post('/:sku')
+  @RequestDto(RenameProductRequest)
+  @UseGuards(EditorGuard)
+  @UseInterceptors(MutationAuditInterceptor)
+  rename(input: RenameProductRequest, context: RequestContext) {
+    productCatalog.rename(input.sku, input.name);
+    context.response.redirect(303, `/products/${encodeURIComponent(input.sku)}?updated=true`);
+  }
+}
+```
+
+An invalid submission keeps the canonical HTTP `400` validation envelope. Its `details` entries
+contain the safe field, source, code, and application-authored validation message; they do not expose
+the submitted value, stack, or internal exception. A successful mutation uses `303 See Other` so the
+browser follows with `GET`, and that destination is matched again by the ordinary HTTP dispatcher.
+Authorization and CSRF policy remain application responsibilities; use the same session/cookie,
+guard, and middleware policies as non-React routes.
+
+This recipe is intentionally different from React Router actions/fetchers, Astro Actions, and
+Next.js Server Actions: fluo does not compile a function reference, own route matching, revalidate a
+loader/client cache, or replace the document response. It is also separate from the experimental
+fluo Server Functions transport. No stable submit-state helper is added in this phase because the
+native form already supplies the complete fallback and `@fluojs/react/client` does not own mutation
+routes or cache invalidation. Applications may add local pending UI after hydration only when the
+real form action and native submission remain intact.
+
 ## Experimental RSC Prototype
 
 > **Experimental contract:** `@fluojs/react/experimental/rsc` can change before an explicit
@@ -483,6 +1028,10 @@ metadata, middleware, guards, interceptors, request scopes, errors, and adapter
 the helper adds the fixed `text/x-component; charset=utf-8` content type and does not create a
 parallel router.
 
+Streamed Flight payloads use the same lifecycle guarantee as stable SSR: an early response-sink
+close or a failed write/drain cancels the unfinished reader exactly once, releases its lock, and
+preserves the sink failure for the ordinary HTTP error pipeline.
+
 ```ts
 import { Controller, Get } from '@fluojs/http';
 import { createReactFlightResponse } from '@fluojs/react/experimental/rsc';
@@ -635,10 +1184,16 @@ This package currently does **not** provide:
 - a Next.js App Router, TanStack route tree, Angular `Routes[]`, file-route scanner, or React-owned
   `routes: []` table
 - automatic client bundle generation
+- href generation for versioned React pages; path-only typegen rejects versioned catalog entries
+  until the catalog can distinguish URI versioning from non-path version strategies
 - filesystem scanning or automatic manifest file discovery; pass an already-loaded manifest value to
   `@fluojs/react/vite`
 - automatic serialization of arbitrary data into `bootstrapScriptContent`
 - Node-only `react-dom/server` pipeable stream root APIs such as `renderToPipeableStream(...)`
+- Next.js-style segment `loading`, `error`, `notFound`, template, or layout ancestry semantics;
+  `@SuspenseFallback(...)` is SSR-descendant Suspense metadata only
+- a generic page error-presentation policy or page-local not-found renderer; optional HTML is a
+  global/application HTTP representation and does not add page ancestry or matching semantics
 
 ## Public API
 
@@ -646,8 +1201,48 @@ This package currently does **not** provide:
 - `Path` — method decorator that writes HTTP `GET` route metadata plus React render metadata.
 - `getReactRouterMetadata` — reads React router marker metadata from a router class.
 - `getReactPathMetadata` — reads React render metadata from a router method.
+- `createReactPageCatalog` — creates a frozen, read-only React page catalog from authoritative
+  compiled HTTP descriptors without participating in matching or dispatch.
+- `ReactPageCatalogEntry` — type-only bootstrap-resolved page descriptor with effective HTTP
+  method/path/version/params plus the originating router and handler.
+- `@fluojs/react/typegen` subpath — `generateReactPageTypes(...)`,
+  `inspectReactPageTypeArtifact(...)`, `REACT_PAGE_TYPEGEN_ARTIFACT_VERSION`,
+  `ReactPageTypeArtifactInspection`, `ReactPageTypegenError`, `REACT_PAGE_TYPEGEN_ERROR_CODES`, and
+  `ReactPageTypegenErrorCode` for deterministic path-only declarations, versioned artifact checks,
+  absolute href builders, route-bound `Link` props, and typed `push`/`replace` methods without
+  widening the package root or adding a runtime route table.
 - `ReactModule` — runtime-neutral module facade whose `forRoot(...)` registers React routers through
   the existing fluo module/controller metadata path.
+- `REACT_PAGE_RENDERER` — dependency-injection token for the application page renderer registered by
+  `ReactModule.forRoot({ renderPage })`.
+- `ReactPageRenderer` — type-only application callback that composes a `ReactElement` and active
+  `ReactRenderContext` plus resolved `ReactRenderPolicies` into an existing `ReactServerEntry`.
+- `PageLayout`, `SuspenseFallback`, and `PageMetadata` — class-or-method decorators that record
+  renderer-only component references or one synchronous metadata factory.
+- `resolveReactPageMetadata` — composes ordered metadata factories for the active request without
+  exposing response mutation authority.
+- `createReactPageMetadataElements` — creates ordinary escaped React title, meta, and link elements
+  from one resolved metadata snapshot.
+- `getReactRenderPolicies` — resolves inherited class/method policies in outer-to-inner order.
+- `REACT_RENDER_POLICY_DIAGNOSTIC_CODES` and `ReactRenderPolicyConfigurationError` — stable
+  bootstrap diagnostics for duplicate, invalid-target, invalid-reference, and missing-renderer policy
+  declarations.
+- `ReactPageLayout`, `ReactPageLayoutProps`, `ReactSuspenseFallback`,
+  `ReactSuspenseFallbackProps`, `ReactRenderPolicies`, and `ReactRenderPolicyDiagnosticCode` —
+  type-only render-policy composition contracts.
+- `ReactPageMetadata`, `ReactPageMetadataFactory`, `ReactPageMetadataContext`, `ReactPageMeta`, and
+  `ReactPageLink` — type-only bounded page metadata contracts.
+- `REACT_SSR_DIAGNOSTIC_PHASES` and `REACT_SSR_DIAGNOSTIC_CODES` — stable machine-readable SSR
+  lifecycle phase and diagnostic code constants.
+- `ReactSsrDiagnosticError` — typed pre-commit configuration/render failure with stable `code` and
+  `phase` metadata.
+- `ReactSsrDiagnostic`, `ReactSsrDiagnosticCode`, `ReactSsrDiagnosticErrorOptions`,
+  `ReactSsrDiagnosticHandler`, and `ReactSsrDiagnosticPhase` — type-only contracts for application
+  diagnostics tooling.
+- `createReactErrorRepresentationProvider` — adapts an application React error document renderer to
+  the HTTP-owned HTML provider seam while buffering before commit.
+- `ReactErrorDocumentRenderer` and `ReactErrorRepresentationProviderOptions` — type-only contracts
+  for the application callback, optional availability constraint, and renderer override.
 - `createReactServerEntry` — creates a runtime-neutral React server entry returned by page handlers
   for Web Streams SSR.
 - `renderReactResponse` — renders one React server entry to a fluo HTML response with lazy
@@ -655,7 +1250,7 @@ This package currently does **not** provide:
 - `ReactAssetMap`, `ReactBootstrapAsset`, and `ReactBootstrapScriptDescriptor` — type-only contracts
   for build-produced asset maps and React DOM bootstrap script/module entries.
 - `ReactModuleOptions` — options accepted by `ReactModule.forRoot(...)`, including `controllers`,
-  `imports`, `providers`, `exports`, and module-level `middleware`.
+  `imports`, `providers`, `exports`, module-level `middleware`, and optional `renderPage` registration.
 - `ReactServerEntry`, `ReactServerEntryOptions`, `ReactServerEntryHeaders`,
   `ReactRecoverableErrorHandler`, `ReactRecoverableErrorContext`, `ReactRenderContext`,
   `ReactReadableStream`, `ReactReadableStreamRenderer`, `ReactReadableStreamRenderOptions`, and
@@ -664,28 +1259,43 @@ This package currently does **not** provide:
 - `ReactRouterMetadata`, `ReactPathMetadata`, `ReactPathOptions` — type-only metadata contracts for
   diagnostics and future rendering integration.
 - `@fluojs/react/vite` subpath — `createReactViteAssetManifest(...)` plus
-  `ReactViteBuildManifest`, `ReactViteBuildManifestChunk`, `ReactViteManifestOptions`,
-  `ReactViteManifestDiagnostic`, `ReactViteAssetManifest`, `ReactViteHydrationOptions`,
-  `ReactViteJavaScriptAssets`, `ReactViteBootstrapData`, and `ReactViteResolvedEntry` for parsing
-  Vite manifests into the stable hydration asset contract without importing Vite from the root.
+  `ReactViteBuildManifest`, `ReactViteBuildManifestChunk`, `ReactViteManifestEntries`,
+  `ReactViteManifestOptions`, `ReactViteManifestDiagnostic`, `ReactViteManifestDiagnosticCode`,
+  `ReactViteAssetManifest`, `ReactViteAssetManifestResult`, `ReactViteHydrationOptions`,
+  `ReactViteJavaScriptAssets`, `ReactViteBootstrapData`, and `ReactViteResolvedEntry` for parsing Vite
+  manifests into the stable hydration asset contract without importing Vite from the root.
 - `@fluojs/react/client` subpath — `Link`, `ReactClientRouterProvider`,
-  `createReactRouteSnapshot(...)`, `useRouter()`, `usePathname()`, `useParams()`,
-  `useSearchParams()`, `useNavigation()`, and `useRouterState()` for progressive HTTP-first browser
-  navigation without widening the root package or adding a client route grammar.
-- `@fluojs/react/experimental/rsc` subpath — `inspectReactRscEnvironment(...)`,
-  `createReactRscManifest(...)`, `createReactFlightResponse(...)`, exact-version and Flight content
-  type constants, diagnostics, client-reference/server-module mapping types, signed
-  `createReactServerFunctionRegistry(...)`, explicit `createReactServerFunctionClient(...)`, stable
-  Server Function error codes, and related transport types without any root or stable-client
-  re-export.
+  `ReactClientNavigationError`, `ReactClientRouterContextError`, `createReactRouteSnapshot(...)`,
+  `useRouter()`, `usePathname()`, `useParams()`, `useSearchParams()`, `useNavigation()`, and
+  `useRouterState()` for progressive HTTP-first browser navigation without widening the root package
+  or adding a client route grammar. Type exports are `LinkProps`, `ReactClientNavigationErrorCode`,
+  `ReactClientRouterProviderProps`, `ReactNavigationSnapshot`, `ReactNavigationStatus`,
+  `ReactNavigationType`, `ReactReadonlySearchParams`, `ReactRouteSnapshot`,
+  `ReactRouteSnapshotInput`, and `ReactRouter`.
+- `@fluojs/react/experimental/rsc` subpath — runtime exports are `REACT_RSC_DIAGNOSTIC_CODES`,
+  `REACT_RSC_FLIGHT_CONTENT_TYPE`, `REACT_RSC_SUPPORTED_VERSION`,
+  `REACT_SERVER_FUNCTION_ERROR_CODES`, `REACT_SERVER_FUNCTION_REQUEST_HEADER`,
+  `ReactServerFunctionClientError`, `ReactServerFunctionConfigurationError`,
+  `createReactFlightResponse(...)`, `createReactRscManifest(...)`,
+  `createReactServerFunctionClient(...)`, `createReactServerFunctionRegistry(...)`, and
+  `inspectReactRscEnvironment(...)`. Type exports are `ReactFlightPayload`, `ReactFlightResponse`,
+  `ReactFlightResponseHeaders`, `ReactFlightResponseOptions`, `ReactRscBuildCapabilities`,
+  `ReactRscClientReference`, `ReactRscClientReferenceManifest`, `ReactRscDiagnostic`,
+  `ReactRscDiagnosticCode`, `ReactRscEnvironmentOptions`, `ReactRscManifest`,
+  `ReactRscManifestInput`, `ReactRscManifestResult`, `ReactRscRuntimeCapabilities`,
+  `ReactRscServerClientModuleMap`, `ReactRscSupportResult`, `ReactServerFunctionClient`,
+  `ReactServerFunctionClientOptions`, `ReactServerFunctionErrorCode`, `ReactServerFunctionFetch`,
+  `ReactServerFunctionHandler`, `ReactServerFunctionReference`, `ReactServerFunctionRegistry`,
+  `ReactServerFunctionRegistryOptions`, `ReactServerFunctionResponse`, and
+  `ReactServerFunctionValue`. None are re-exported from the root or stable client subpath.
 
 ## Related Packages
 
 - `@fluojs/core`: Provides the standard `@Module` decorator used by the scaffold.
 - `@fluojs/http`: Provides the controller, route, DTO, guard, interceptor, header, and version
   metadata pipeline reused by `@Router(...)` and `@Path(...)`.
-- `@fluojs/runtime`: Future React integration work is expected to compose with runtime bootstrap
-  contracts without widening the root import boundary.
+- `@fluojs/runtime`: Registers the optional HTTP error representation together with the existing
+  application bootstrap contracts without widening the React root import boundary.
 - `@fluojs/vite`: Owns Vite's TC39 decorator transform boundary. It does not parse React hydration
   manifests; use `@fluojs/react/vite` for React server/client asset mapping.
 - Application-selected Flight renderer: Encodes RSC payloads and consumes renderer-specific build
@@ -702,6 +1312,7 @@ This package currently does **not** provide:
 - `packages/react/src/experimental/rsc.test.ts`
 - `packages/react/src/experimental/rsc-diagnostics.test.ts`
 - `packages/react/src/experimental/rsc-flight.test.ts`
+- `packages/react/src/experimental/rsc-flight-stream-lifecycle.test.ts`
 - `packages/react/src/experimental/rsc-manifest.test.ts`
 - `packages/react/src/experimental/server-functions-server.ts`
 - `packages/react/src/experimental/server-functions-client.ts`
@@ -712,7 +1323,15 @@ This package currently does **not** provide:
 - `packages/react/src/decorators.ts`
 - `packages/react/src/server-entry.ts`
 - `packages/react/src/render.ts`
+- `packages/react/src/error-representation.ts`
+- `packages/react/src/error-representation.test.ts`
 - `packages/react/src/module.ts`
+- `packages/react/src/page-renderer.ts`
+- `packages/react/src/render-policy.ts`
+- `packages/react/src/render-policy-metadata.ts`
+- `packages/react/src/render-policy.test.ts`
+- `packages/react/src/page-metadata.ts`
+- `packages/react/src/page-metadata.test.ts`
 - `packages/react/src/render.test.ts`
 - `packages/react/src/dispatcher-ssr.test.ts`
 - `packages/react/src/hydration-assets.test.ts`