@rshono/core 1.0.0-rc.2 → 1.0.0-rc.21

package/README.md

@@ -1,36 +1,58 @@
-# rshono
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rshono/rshono/main/logo.svg" alt="" width="72" height="72" />
+</p>
 
-Minimalist web framework — [Hono](https://hono.dev) + [Rspack](https://rspack.rs) + [React Server Components](https://react.dev/reference/rsc/server-components).
+<h1 align="center">@rshono/core</h1>
 
-> **Alpha.** The framework itself is covered by an end-to-end suite (see [Testing](#testing)), but it
-> is built on Rspack's experimental RSC support (`rspack.experiments.rsc`) and `react-server-dom-rspack`,
-> which is still `0.0.x`. Those two move underneath us, so `@rspack/core` and `react-server-dom-rspack`
-> are pinned to exact versions and a release of rshono is what moves them.
+<p align="center">
+  Minimalist web framework —
+  <a href="https://hono.dev">Hono</a> +
+  <a href="https://rspack.rs">Rspack</a> +
+  <a href="https://react.dev/reference/rsc/server-components">React Server Components</a>.
+</p>
 
-One required file (`src/routes.ts`), one optional file (`src/server.ts`), and you get a dev server with HMR, streaming SSR with RSC hydration, server actions with progressive enhancement, soft navigation, build-time prerendering, and hard env/secret safety.
+One required file (`src/routes.ts`), one optional file (`src/server.ts`), and you get a dev server with HMR,
+streaming SSR with RSC hydration, server actions with progressive enhancement, soft navigation, build-time
+prerendering, and hard env/secret safety.
+
+> **Release candidate.** The framework itself is covered end to end (see [Testing](#testing)) and its API is
+> settled. What is not settled underneath it: Rspack's RSC support is an experimental API
+> (`rspack.experiments.rsc`) and `react-server-dom-rspack` has not reached 1.0, so its own minor bumps are
+> breaking by convention. Both are pinned to exact versions — in the manifests and in workspace overrides —
+> and a release of rshono is what moves them, so an upstream change reaches you as a tested release rather
+> than as a broken install. That is the whole of the caveat, and it is the reason to read the
+> [changelog](../../CHANGELOG.md) before upgrading.
+
+**Full documentation: [rshono.com/docs](https://www.rshono.com/docs).**
 
 ```bash
-npm create @rshono@latest my-app   # scaffold one, with a deploy target and tooling of your choosing
+npx @rshono/create@latest my-app   # scaffold one, with a deploy target and tooling of your choosing
 ```
 
 ```bash
 rshono dev     # dev server with HMR (default port 3000)
-rshono build   # production build: client + server bundles + SSG
+rshono build   # production build: client + server bundles + prerendered pages
 rshono start   # run the production build
 ```
 
+`--port` / `PORT` sets the port for `dev` and `start`. **`HOST` applies to `start` only** — `dev` always binds
+`127.0.0.1`, because its source maps embed the original source of your `'use server'` modules, and it warns if
+you set one. `--config <path>` points `build` at another config file.
+
 ## Project layout
 
 ```
-rshono.config.ts   optional — every field has a default (see Configuration)
+rshono.config.ts   optional — every field has a default
 public/            optional — served verbatim at the web root
 src/
   routes.ts        required — the route table
   server.ts        optional — a Hono sub-app mounted ahead of the page routes
-  …               everything else is yours to arrange
+  …                everything else is yours to arrange
 ```
 
-Only the two files under `src/` mean anything to the framework; there is no convention attached to any other name or directory. `@/…` resolves to `src/…` in both compilers, so add the matching `paths` to your `tsconfig.json` if you use it — relative, and with no `baseUrl`, which TypeScript 7 removed:
+Only those two files under `src/` mean anything to the framework; no other name or directory carries a
+convention. `@/…` resolves to `src/…` in both compilers, so add the matching `paths` to `tsconfig.json` if
+you use it — relative, and with no `baseUrl`, which TypeScript 7 removed:
 
 ```json
 { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
@@ -58,13 +80,15 @@ export const routes = defineRoutes({
 });
 ```
 
-`routes.ts` only ever runs on the server — importing server-only modules from it (e.g. inside `staticPaths`) is safe. A plain array (no special pages) is accepted as shorthand.
+`routes.ts` only ever runs on the server, so importing server-only modules from it (inside `staticPaths`,
+say) is safe. A plain array, with no special pages, is accepted as shorthand.
+[Routing docs](https://www.rshono.com/docs/routing).
 
 ## Pages are server components
 
-Every page module **default-exports a server component** — nothing else. Under the hood each page carries Rspack's `'use server-entry'` directive (it attaches the page's client JS/CSS assets to the component — per-page code splitting with no asset manifest), but the framework **injects it automatically** for every component referenced with the inline `component: () => import('…')` thunk form in routes.ts. This also works for routes added while the dev server is running.
-
-If a component is wired up some other way (variable indirection, barrel re-exports, computed specifiers), write `'use server-entry'` as the first line of the page module yourself — a manually written directive is always respected. The framework throws a descriptive error when neither happened.
+Every page module default-exports a server component — nothing else. It renders the whole document
+(`<html>…</html>`), may be `async`, and awaits its data directly. Interactive parts are `'use client'`
+components the page imports; only those ship JavaScript.
 
 ```tsx
 import type { PageProps } from '@rshono/core';
@@ -77,14 +101,22 @@ export default async function Profile({ params, ctx }: PageProps<'/profile/:id'>
 }
 ```
 
-- Pages receive `{ url, params, ctx }` (`PageProps<'/profile/:id'>` types `params.id`). `url` is a real `URL` — read `url.pathname` and `url.searchParams` off it — and the pair matches what a `'use client'` component gets from `useNavigation()`, so a read moves across the line unchanged.
-- **`ctx` is the request context** — cookies, headers, env, middleware variables, the proxy-aware URL. It is the same object `getContext()` returns from `@rshono/core/server`, handed over so a page needs no import; reach for `getContext()` in the places that get no props (a nested server component, a `'use server'` action). Type `ctx.var` / `ctx.env` for your app by passing its Hono `Env`: `PageProps<'/profile/:id', MyEnv>`.
-- Reading `ctx` on a **`render: 'static'`** page throws — a page rendered once at build time has no request to read. Use `params` and `url`, which are available either way, or make the route `render: 'dynamic'`. One quiet caveat: a prerendered `url` is the build-time one (`siteUrl` + the path, no query), and that one file answers every request whatever its own query — so `url.searchParams` is always empty there. Read the query with `useNavigation().url` on the client instead.
-- Pages render the **entire document** (`<html>…</html>`), usually via a shared layout component.
-- Interactive parts are `'use client'` components imported by the page; only those ship JavaScript.
-- A fully interactive page is a thin server component wrapping a `'use client'` component.
-- Page props are **server-only and never serialized** — React puts a server component's output on the wire, not its props. `ctx` is additionally non-enumerable, which keeps it out of React's dev-only debug payload (an enumerable one would ship the whole Hono context, bindings included, to the browser in dev).
-- **`ctx` cannot cross into a `'use client'` component**; it wraps the live request and response, which don't exist in the browser. Passing it explicitly (`<Counter ctx={ctx} />`) fails the render with React's _"Only plain objects … can be passed to Client Components"_, naming the prop. Spreading page props instead (`<Counter {...props} />`) drops it silently, since a spread copies enumerables only — though that spread fails anyway on `url`, which is enumerable and just as unserializable. Either way: read what you need on the server and pass plain values down (`url.href`, not `url`).
+- Pages receive `{ url, params, ctx }` — `PageProps<'/profile/:id'>` types `params.id`, and `url` is a real
+  `URL`. The same pair reaches a `'use client'` component from `useNavigation()`, so a read moves across the
+  boundary unchanged.
+- **`ctx` is the request context** — `ctx.req`, cookies, env, middleware variables, the proxy-aware URL. It is
+  the same object `getRequestContext()` returns from `@rshono/core/server`, handed over so a page needs no
+  import. Reading it on a `render: 'static'` page throws: a page rendered once at build time has no request.
+  A page can only _read_ it — `cookies.set` and `setHeader` throw there, because a page streams and its
+  response head is already committed; set them from a `'use server'` action or from middleware instead.
+- Page props are server-only and never serialized, and `ctx` cannot cross into a client component. Read what
+  you need on the server and pass plain values down (`url.href`, not `url`).
+- The framework injects Rspack's `'use server-entry'` directive for every component referenced with the
+  inline `component: () => import('…')` thunk — that is what attaches the page's JS and CSS to it, so code
+  splitting needs no asset manifest. Wire a component up some other way and you write the directive
+  yourself; the framework throws a descriptive error when neither happened.
+
+[Pages docs](https://www.rshono.com/docs/pages).
 
 ## Server actions
 
@@ -95,179 +127,337 @@ export default async function Profile({ params, ctx }: PageProps<'/profile/:id'>
 export async function createUser(data: { name: string; email: string }) { … }
 ```
 
-Call them directly from client code (typed args and result), or wire them to `<form action>` / `useActionState` — forms keep working before hydration and with JavaScript disabled (progressive enhancement). Every action response carries a fresh page payload, so server-rendered UI updates automatically after mutations.
-
-## Full Hono underneath
+Call them directly from client code (typed args and result), or wire them to `<form action>` /
+`useActionState` — forms keep working before hydration and with JavaScript disabled. Every action response
+carries a fresh page payload, so server-rendered UI updates after a mutation.
+**Every `'use server'` export is a public HTTP endpoint**, so authenticate, authorize and validate inside the
+action. [Server actions docs](https://www.rshono.com/docs/pages#server-actions), and
+[how to use them](https://www.rshono.com/docs/usage).
 
-- `{ type: 'endpoint' }` routes export a Hono `handler` from a server module (it only ever runs on the server).
-- `src/server.ts` may default-export a whole Hono sub-app: any method, streaming, cookies, middleware. `export type AppType = typeof server` gives end-to-end type safety with `hono/client`.
-- The sub-app is mounted at `/` **ahead of the page routes**, so its middleware (auth, logging, trailing-slash) wraps page requests too. The flip side: a _terminal_ handler in `src/server.ts` at the same path as a page route shadows the page.
+Rspack compiles an app's whole `'use server'` graph into **one** server module, and calling any action loads
+it — so a module that throws while it evaluates takes every action in the app with it, not just its own.
+Nothing on the server imports these modules until an action is called, which used to make that a green build
+followed by a 500 on the first click. `rshono build` now loads them and warns if one will not, and at run
+time a failure to load is reported as an action fault, not answered as a bad request.
 
-## Styling
-
-- `import './styles.css'` from any component. Rspack's native CSS pipeline compiles it, and the import attaches the stylesheet to the importing page's assets — so CSS is code-split per route and arrives with the page that needs it, `<link>`ed in the streamed HTML rather than fetched after hydration. `*.module.css` gets a class map.
-- **There is no PostCSS in the framework**, and no dependency on any of it — native CSS is fast, and it is everything a plain stylesheet needs. What it cannot do is read CSS that isn't finished yet: `@import 'tailwindcss'`, `@theme` and `@apply` are all parse-time nonsense to it. A stylesheet that needs a plugin puts the plugin in front of that parser itself, through the [`rspack` hook](#configuration-rshonoconfigts), and installs the two packages a PostCSS pass takes.
-- **Tailwind** is exactly that, and nothing else:
-
-  ```bash
-  npm i -D tailwindcss @tailwindcss/postcss postcss postcss-loader
-  ```
-
-  ```ts
-  // rshono.config.ts — the hook is called once per compiler, so this reaches both graphs
-  export default defineConfig({
-    rspack(config) {
-      config.module!.rules!.push({ test: /\.css$/i, use: ['postcss-loader'], type: 'css/auto' });
-    },
-  });
-  ```
-
-  ```js
-  // postcss.config.mjs — the plugin list, which postcss-loader finds on its own
-  export default { plugins: { '@tailwindcss/postcss': {} } };
-  ```
-
-  ```css
-  /* src/styles.css */
-  @import 'tailwindcss';
-  ```
-
-  Keep `type: 'css/auto'` rather than `'css'`, or `*.module.css` stops being a CSS module. `npm create @rshono@latest --tailwind` writes all four of these for you.
-
-## Static files
+## Full Hono underneath
 
-- Drop anything you want served verbatim into `public/` — it's mounted at the **web root**, so `public/favicon.ico` → `/favicon.ico`, `public/robots.txt` → `/robots.txt`, `public/.well-known/…` resolves too. This is the home for the conventional files browsers and crawlers request by path.
-- It's a **fallback**: your routes always win, and unmatched paths still fall through to the `notFound` page — so a `public/` file never shadows a real route. `build` copies `public/` into `dist/` so a deployed build is self-contained.
-- Hashed bundle output is served separately under `/_static/` with long-lived immutable caching; `public/` files get a short `max-age` (and `no-cache` in dev).
+- `{ type: 'endpoint' }` routes export a Hono `handler` from a server module.
+- `src/server.ts` may default-export a whole Hono sub-app: any method, streaming, cookies, middleware.
+  `export type AppType = typeof server` gives end-to-end type safety with `hono/client`.
+- It is mounted at `/` **ahead of the page routes**, so its middleware (auth, logging, trailing-slash) wraps
+  page requests too. The flip side: a _terminal_ handler at the same path as a page route shadows the page.
 
-## Prerendering (`render: 'static'`)
+[Hono docs](https://www.rshono.com/docs/hono).
 
-A static route is built once and served from disk in **both** representations — `index.html` for a hard load, `index.rsc` for the flight payload a soft navigation asks for. Serving only the document would mean every in-app click re-rendered a page the build had already produced, so the prerender would pay off for crawlers and nobody else. Both carry a weak `ETag`, so a revalidation costs a 304.
+## Styling
 
-Set **`siteUrl`** if your static pages build absolute URLs — a canonical tag, an `og:url`, an absolute link. A prerendered file is one set of bytes handed to everyone, so there is no request to read a `Host` from and the origin has to be decided at build time; without `siteUrl` it is `http://localhost`, and the build warns. Dynamic routes are unaffected — they resolve the URL per request, `siteUrl` or not.
+`import './styles.css'` from any component. Rspack's native CSS pipeline compiles it, and the import
+attaches the stylesheet to the importing page — so CSS is code-split per route and `<link>`ed in the streamed
+HTML rather than fetched after hydration. `*.module.css` gets a class map.
 
-If a page can't be prerendered (its `staticPaths` is missing, or it didn't render cleanly at build time) the build says so and that route falls back to rendering per request.
+**There is no PostCSS in the framework**, so a stylesheet that needs a plugin brings one, through the
+[`rspack` hook](#configuration-rshonoconfigts). Tailwind is exactly that and nothing else — four packages, a
+`postcss.config.mjs` and one rule; `npx @rshono/create@latest --tailwind` writes all of it.
+[Styling docs](https://www.rshono.com/docs/styling).
 
 ## Env & secret safety
 
-The client/server boundary is the RSC directives — `'use client'` and `'use server'` — not filenames, and `process.env` access follows it. There is no `*.server` naming convention.
+The boundary is the RSC directives — `'use client'` and `'use server'` — not filenames, and `process.env`
+follows it.
+
+- In the **client bundle** `process.env` is _replaced at build time_ with a literal holding only `NODE_ENV`
+  and `PUBLIC_`-prefixed variables. A stray `process.env.DATABASE_URL` in client code compiles to
+  `undefined`; the value cannot ship. That is a build-time substitution, not tree-shaking, and it covers
+  `node_modules` too.
+- Your `'use client'` modules see the same `PUBLIC_`-only view **while being SSR'd**, so a secret read there
+  renders empty instead of leaking into the HTML stream, and SSR output still agrees with hydration.
+- Server components and `'use server'` actions read the real `process.env`. Anything a server component
+  _renders_ is public by definition.
+- `.env.local` and `.env` are loaded automatically; the real environment wins.
 
-- **Client bundle**: `process.env` is _replaced at build time_ with a literal containing only `NODE_ENV` and `PUBLIC_`-prefixed variables. A stray `process.env.DATABASE_URL` in client code compiles to `undefined` — the value cannot ship. This is a hard guarantee, not tree-shaking, and it covers your `node_modules` too.
-- **`'use client'` modules are also SSR'd on the server**, and there they see the same `PUBLIC_`-only view. A `process.env.SECRET` in a client component renders empty instead of leaking into the HTML stream, and SSR output always agrees with hydration. This SSR-side shadowing is scoped to your own `src/` — a _third-party_ client component that reads `process.env` during SSR sees the real environment, so treat a dependency that does that as you would any other dependency handling secrets.
-- **Server components and `'use server'` actions read the real `process.env`.** They run only on the server — server components stay in the server graph, actions compile to server references — so a secret read there never reaches the browser. Read secrets in server code and pass derived data down.
-- `.env.local` and `.env` are loaded automatically (real environment wins).
-- Anything a server component _renders_ is public by definition — whatever you put in the tree ships in the flight payload.
-- Keeping a server-only module out of the client bundle is the module graph's job: import it only from server code. For a hard failure if that ever slips, add React's `server-only` package — the RSC layer resolves its `react-server` condition, so importing it from client code throws.
+[Environment and secrets](https://www.rshono.com/docs/configuration#environment-and-secrets).
 
 ## Configuration: rshono.config.ts
 
-An optional `rshono.config.ts` (`.js` / `.mjs` also work) at the project root tunes the framework. Every field is optional; delete the file to accept all defaults.
+Optional (`.js` / `.mjs` also work). Every field is optional; delete the file to accept all defaults.
 
 ```ts
 import { defineConfig } from '@rshono/core';
 
 export default defineConfig({
-  deploy: 'node', // hosting platform to build for — see Deployment (--deploy or RSHONO_DEPLOY override)
+  deploy: 'node', // hosting platform to build for (--deploy or RSHONO_DEPLOY override)
   siteUrl: 'https://example.com', // public origin, baked into prerendered pages' absolute URLs
-  port: 3000, // default port for dev/start (--port or PORT env override)
-  host: '0.0.0.0', // bind address for start (HOST env overrides)
   trustProxy: false, // honour X-Forwarded-Host/-Proto — only behind a proxy you control
-  checkOrigin: true, // CSRF origin check on server-action POSTs
-  allowedOrigins: [], // extra origins allowed to post actions, e.g. ['https://admin.example.com']
-  csp: false, // strict per-request-nonce Content-Security-Policy
-  cspDirectives: {}, // widen the built-in CSP, e.g. { 'img-src': "'self' https://cdn.example.com" }
-  bodySizeLimit: '1mb', // request body cap: '512kb' | 4_000_000 | false to disable
-  renderTimeout: 10_000, // ms deadline for a request (action + flight + SSR)
-  compress: true, // gzip compressible responses (streaming-safe)
   rspack(config, { isServer, isDev }) {
     return config; // escape hatch: mutate the generated Rspack config
   },
 });
 ```
 
-`defineConfig` is an identity helper for editor autocomplete; `export default { … } satisfies RSHonoConfig` works too. `deploy`/`port`/`host`/`rspack` are consumed by the CLI; the framework settings (`trustProxy`, `checkOrigin`, `allowedOrigins`, `csp`, `cspDirectives`, `bodySizeLimit`, `renderTimeout`, `compress`) are resolved from this file at build time and **compiled into the server bundle** — there is no parallel env-var interface for them (environment variables are for secrets). Changing one of these settings means a rebuild. The two deployment-conventional exceptions stay env-overridable: `--port`/`PORT` and `HOST` win over the file, which wins over the built-in default. Point `rshono build` at a different config with `--config <path>`.
-
-## Security & hardening
-
-- **Every `'use server'` export is a public HTTP endpoint.** That's the RSC model, not an rshono choice: the client is handed an id for each action and can call it with whatever arguments it likes. The CSRF check below proves a request came from your own site — it says nothing about _who_ sent it. Authenticate and authorize inside the action (and validate its arguments) exactly as you would in a route handler.
-- **CSRF**: server-action POSTs are origin-checked automatically — a cross-origin `Origin` (compared against your own host) is rejected with 403, as is anything the browser labels `Sec-Fetch-Site: cross-site`/`same-site`. A browser-asserted `Sec-Fetch-Site: same-origin` is accepted directly, which is what keeps the check from misfiring behind a proxy that rewrites `Host`. Applies to both client-initiated calls and no-JS form posts. Turn it off with `checkOrigin: false` behind a gateway that already enforces it, or list trusted cross-origins in `allowedOrigins` (full origins or bare hosts; a malformed entry fails the build).
-- **Proxy headers are not trusted by default.** `X-Forwarded-Host` / `-Proto` are client-supplied, so honouring them blindly lets anyone who can reach the server dictate the origin of every absolute URL the app builds (`getContext().url`, a page's `url` prop) — poisoning canonical tags, emails and redirects, and any shared cache in front. Set `trustProxy: true` only when a proxy you control sets those headers; `rshono dev` forces it on for its own localhost-bound proxy.
-- **Request deadline**: every request races a timeout (`renderTimeout`, default 10000) and the client-disconnect signal — covering the server action as well as flight + SSR — so neither a hung data fetch nor a hung mutation can pin sockets open.
-- **Request-body limit**: request bodies are capped (`bodySizeLimit`, default 1048576 = 1 MiB) before they're buffered into memory — oversized bodies are rejected with `413 Payload Too Large`. This covers **every** route, not just server actions: `{ type: 'endpoint' }` routes and the `src/server.ts` sub-app are equally exposed the moment they call `.json()` or `.formData()`. An over-cap `Content-Length` is refused up front; bodies that omit it (chunked) are cut off mid-stream. Set to `false`/`0` to disable (e.g. behind a proxy that already enforces a limit, or to stream a large upload yourself). Raise it for large multipart uploads.
-- **Baseline response headers**: `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin` and `X-Frame-Options: SAMEORIGIN` on every response, unconditionally. The framing header is the floor for everyone who hasn't opted into `csp` — that policy's `frame-ancestors 'none'` is stricter and takes precedence where both apply. Set any of them in your own middleware to override.
-- **Caching defaults**: a dynamic page is answered with `Cache-Control: private, no-cache` — a page is request-specific by default (cookies, session, headers), and with no directives at all a shared cache is free to store one user's page and serve it to the next. `private` forbids exactly that, and `no-cache` makes the browser revalidate rather than re-show a stale personalised page; neither disables bfcache the way `no-store` would. Set your own value (from middleware, or `getContext().header(…)`) and it is left alone. Prerendered pages keep `public, max-age=300` and carry a weak `ETag`, so a revalidation costs a 304 instead of the page.
-- **`Vary: Accept` on page responses.** One URL answers with an HTML document or a flight payload depending on `Accept`. Without `Vary` a cache keyed on the URL alone will eventually hand a document to a soft navigation that asked for flight — a hard reload at best. Compression appends `Accept-Encoding` to the same header rather than replacing it.
-- **CSP (opt-in)**: set `csp: true` to send a strict per-request-nonce `Content-Security-Policy` with every HTML document (nonce stamped on bootstrap scripts, inlined flight payload, and dynamically loaded chunks). Beyond `default-src 'self'` it also closes the gaps `default-src` doesn't cover — `base-uri`, `object-src`, `frame-ancestors`, `form-action` — so it blocks framing and third-party assets until you widen it with `cspDirectives` (the nonce is always re-appended to `script-src`, and `''` drops a directive). While enabled, the **document** for a `render: 'static'` route is rendered per request — a prerendered file can't carry a per-request nonce. Its flight payload never carries one, so soft navigations are still served from the prerender.
-- **Error reporting**: every error the framework catches — a thrown action, a failed render, SSR falling over, anything reaching the top-level handler — goes through one funnel. Register a handler at the top level of `src/server.ts` to send them somewhere real; they keep going to `stderr` either way, and a handler that throws is caught rather than failing the request.
+That is the whole file. It holds what the **build** decides; per-request security is Hono middleware in
+`src/server.ts`, which is mounted ahead of the page routes and so wraps renders and server actions too:
 
-  ```ts
-  // src/server.ts
-  import { onServerError } from '@rshono/core/server';
-
-  onServerError((error, { source, request }) => {
-    Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });
-  });
-  ```
-
-- **Error responses**: thrown server-action errors are logged server-side and redacted in the production payload (React sends no message or digest for them) — so return values, not throws, for anything the user should see. Custom 404/500 pages are real server components declared in routes.ts (`notFound` / `error`); the error page's `error` prop is message-only in production, message + stack in dev.
-- **No blank screens.** Three fallbacks behind the `error` page, so a failure is always something you can read:
-  - An **uncaught client-side render error** makes React tear down its root — which here is the whole `document`, so the page would go genuinely white with the reason only in the console. The runtime paints a fatal overlay over it instead: full stack and component stack in dev, a generic notice plus a reload button in production (the dev detail is compiled out of the production bundle).
-  - If **SSR fails before the shell is sent**, the `error` page can't be reached either, so the framework answers with its own visible 500 document — the real message and stack in dev, generic in production. It deliberately attaches no client runtime: the flight payload came from the same failed render, so hydrating it would tear the document down and blank the message.
-  - A **client bootstrap failure** (a truncated or malformed initial payload) is reported and surfaced rather than becoming a silent unhandled rejection.
-
-## Testing
-
-`pnpm --filter @rshono/core test` builds the package and runs everything that doesn't need a browser:
-
-- **unit** — the parsers and path maths (`bodySizeLimit`, `allowedOrigins`, SSG paths and traversal, control-signal digests, page-file scanning, `Vary`/`ETag` helpers). Imports the built `dist/`, so it also proves the published output loads in plain Node.
-- **compression** — that gzip does not swallow a streamed response: a chunk the renderer flushes has to reach the client while the response is still open, which is the one property the platform `CompressionStream` would quietly break.
-- **production e2e** — builds `examples/rs-basic`, boots the real production server, and asserts pages, flight protocol, actions (client + progressive enhancement), CSRF rejection, secret stripping in bundles _and_ rendered HTML, SSG output with `ETag`/304, cache and security headers, and error reporting. Settings baked into the bundle (CSP, CSRF allowlist/origin-check, body-size cap) each get their own build from a fixture config (`test/fixtures/`, via `rshono build --config`).
-- **minimal app** — a fixture with `src/routes.ts` and nothing else: no `server.ts`, no `public/`, no config, no `notFound`/`error` pages. Everything the docs call optional, actually left out.
-- **postcss** — a Tailwind fixture wiring the loader up through the `rspack` hook, from an `@import "tailwindcss"` nothing could resolve through to compiled utilities in the stylesheet the served page links. The documented four lines, actually run.
-- **dev** — a smoke test through the dev server's worker + proxy.
+```ts
+// src/server.ts
+import { publicUrl } from '@rshono/core/server';
+import { bodyLimit } from 'hono/body-limit'; // https://hono.dev/docs/middleware/builtin/body-limit
+import { csrf } from 'hono/csrf'; // https://hono.dev/docs/middleware/builtin/csrf
+import { NONCE, secureHeaders } from 'hono/secure-headers'; // https://hono.dev/docs/middleware/builtin/secure-headers
+
+// Caps a body before anything buffers it — pages, actions and your own handlers alike. 413 over cap.
+server.use(bodyLimit({ maxSize: 1024 * 1024 }));
+
+// Rejects a cross-origin POST with 403 before it can reach a server action. `publicUrl(c)` rather
+// than Hono's default, which compares against the address the server was *reached* on — the internal
+// one behind any proxy. It honours `trustProxy`.
+server.use(csrf({ origin: (origin, c) => origin === publicUrl(c).origin }));
+
+// HSTS, COOP, CORP and the rest. `NONCE` in `scriptSrc` makes the CSP per-request: Hono mints the
+// nonce, rshono stamps it onto the bootstrap scripts and the inlined flight payload.
+server.use(secureHeaders({ contentSecurityPolicy: { scriptSrc: ["'self'", NONCE] } }));
+```
 
-`pnpm --filter @rshono/core test:browser` runs the Playwright suite against a production build: hydration, soft navigation, prefetch-on-hover, `useNavigation`, client-initiated actions, boundary fallbacks, scroll restoration and the fatal overlay — the client runtime, which no amount of asserting on HTML can reach.
+`create-rshono` scaffolds the first two. Under `rshono dev` the framework widens `script-src` with
+`'unsafe-eval'` for React Refresh — never in a build — so one policy serves both, and a route with a
+nonce in play falls back to rendering its _document_ per request: fixed bytes cannot carry a fresh nonce.
+Its flight payload has no nonce to go stale and is still served from disk, so `rshono build` marks such a
+page `(flight only)` rather than counting it as fully prerendered. Everything else Hono ships works the same way:
+`cors`, `basicAuth`, `jwt`, `timeout`, `requestId`, `ipRestriction`. A middleware that rejects by
+throwing an `HTTPException` keeps its own status rather than becoming the 500 page.
+[Middleware docs](https://www.rshono.com/docs/hono#security-middleware) · [Hono](https://hono.dev/docs).
+
+`deploy` and `rspack` are consumed by the CLI; `trustProxy` is **compiled into the server bundle** at build
+time, so changing it means a rebuild and there is no parallel env-var interface for it (environment
+variables are for secrets). The port and bind address are deliberately not config fields — on every host
+that runs this, the environment is what sets them. [Configuration docs](https://www.rshono.com/docs/configuration).
+
+The defaults, in short: untrusted proxy headers, `nosniff` / `Referrer-Policy` / `X-Frame-Options` on
+every response (a floor your own `secureHeaders()` overrides),
+`private, no-cache` plus `Vary: RSC` on dynamic pages, `public, max-age=300` and a weak `ETag` on
+prerendered ones, and errors redacted in production — with one `onServerError()` funnel for reporting them
+and three fallbacks (a fatal client overlay, a visible 500 document, a reported bootstrap failure) so a
+failure is never a blank screen.
 
-## How it works
+## Prerendering (`render: 'static'`)
 
-Two coordinated Rspack compilers (native RSC support, `rspack.experiments.rsc`):
+A static route is built once and served from disk in **both** representations — `index.html` for a hard load,
+`index.rsc` for the flight payload a soft navigation asks for — each with a weak `ETag`. Set **`siteUrl`** if
+those pages build absolute URLs: one set of bytes is handed to everyone, so the origin has to be decided at
+build time (without it the build warns and uses `http://localhost`). A page that can't be prerendered — no
+`staticPaths`, or it didn't render cleanly — is reported by the build and falls back to rendering per
+request. [Static rendering docs](https://www.rshono.com/docs/routing#static-rendering).
 
-- **client** (`target: web`) → `dist/static`: hydration runtime, `'use client'` chunks, CSS.
-- **server** (`target: node`) → `dist/server/main.mjs`: the app server itself — a Hono app assembled from your routes, rendered through two layers (RSC layer with the `react-server` condition → flight payload; SSR layer → HTML stream with the payload inlined for hydration).
+## Deployment
 
-In dev, the CLI watches both bundles, runs the server bundle in a worker thread (restarted per rebuild; requests gate on readiness — no dropped connections), and fronts everything on one port with static serving and an SSE channel: client edits hot-apply via react-refresh, server component edits re-fetch the payload in place — browser state survives both.
+`rshono build` targets one platform. Pick it with `deploy` in the config, `--deploy <name>` or
+`RSHONO_DEPLOY`, in that precedence order; the default is `node`. `rshono dev` always runs the Node dev
+server whatever you choose — the target is a property of the build, not of developing.
+
+| `deploy`     | Handoff                          | Assets & prerendered pages                                      | After `build`                               |
+| ------------ | -------------------------------- | --------------------------------------------------------------- | ------------------------------------------- |
+| `node`       | binds a port                     | from `dist/` on disk                                            | `rshono start`                              |
+| `cloudflare` | `{ fetch }` default export       | Workers Assets; prerendered pages read via the `ASSETS` binding | `wrangler deploy`                           |
+| `vercel`     | web handler in a Node function   | CDN for assets; prerendered pages inside the function           | `vercel deploy --prebuilt`                  |
+| `aws-lambda` | streaming handler (Function URL) | from the deployment package                                     | zip `dist/`, handler `dist/server/main.mjs` |
+
+One target per _handoff_ — the thing an app cannot arrange for itself. Everything else about a platform sits
+behind one `DeployRuntime` interface, and `node`, `vercel` and `aws-lambda` share a filesystem implementation.
+Every target streams, which is the bar a new one has to clear.
+
+- **`node` is not only Node.** Anything that runs a Node process runs this build — a VPS, a container, a PaaS.
+  Bun (`bun dist/server/main.mjs`) and Deno (`deno run -A dist/server/main.mjs`) are expected to as well,
+  since the listener is `@hono/node-server`; they had a target each, which held nothing beyond a default
+  export. The suite runs on Node, so treat those two as an expectation rather than a guarantee.
+- **Don't build a handler out of the `app` export.** The entry calls `runtime.serveApp(app)` at module scope,
+  so importing a `node` build binds a port as a side effect. Build for the target you deploy to, and
+  `rshono start` will refuse a build made for another platform.
+- **Streaming is the fragile part of a serverless target, and it fails silently** — `supportsResponseStreaming`
+  on Vercel, `streamifyResponse` plus a `RESPONSE_STREAM` Function URL on Lambda. Getting those right is what
+  the presets are for.
+- **Most of what `vercel` and `aws-lambda` upload is the source map.** `dist/server/main.mjs.map` is roughly
+  three quarters of `dist/server`, and both targets take the whole directory — `vercel` copies it into the
+  function, the `aws-lambda` handoff is "zip `dist/`". That is deliberate: the map is what turns the
+  `onServerError` funnel from minified frames into real ones, and it is never served to anyone. But it is
+  upload weight rather than cold-start weight — nothing parses it unless a stack trace is being mapped — so
+  delete it from the package if size matters more to you than readable production traces.
+- **Prerendered pages are never CDN-served**: one URL answers with a document or a flight payload depending on
+  the `RSC` request header, and a path-keyed CDN cannot choose. `/_static` and `public/` do go straight to the
+  CDN.
+- **`public/` beats a route on `cloudflare` and `vercel`, and loses to it on `node` and `aws-lambda`.** Where
+  the app owns the whole surface, `public/` is mounted after every route and answers only what none of them
+  claimed. Where a CDN sits in front it is part of the static output, so the platform answers from it before
+  the app is invoked — the framework cannot reorder either one. So `public/index.html` beside a page route at
+  `/` serves the file on two targets and renders the page on the other two. `rshono build` warns when a
+  `public/` file lands on a route's path, on the targets where it matters.
+- **The serverless targets bundle your dependencies**; `node` bundles only the ones a `'use client'` component
+  pulls in. A function is an uploaded directory with no `node_modules` to resolve against, so `vercel`,
+  `aws-lambda` and `cloudflare` compile everything in. The cost is that a native addon — or a package that
+  reads its own files off disk — fails the build on those targets rather than the deploy; reach for the
+  `rspack` hook, or deploy to `node`.
+
+  On `node` a server component's dependencies stay external and resolve from `node_modules`, but anything
+  reachable from a `'use client'` component is compiled in on every target. It has to be: the `PUBLIC_`-only
+  `process.env` view is applied by a loader, and a loader cannot run on a module the bundle only imports by
+  name — an external third-party client component would be SSR'd against the real environment. Nothing is
+  given up, since the same module is in the browser bundle and so was always required to be bundleable.
+
+[Deployment docs](https://www.rshono.com/docs/deployment), including Cloudflare bindings and the AWS setup.
 
-In production, `dist/server/main.mjs` is self-contained (React, Hono and the framework are bundled in; your other npm dependencies resolve from `node_modules`): `rshono start` or any process manager running `node dist/server/main.mjs`.
+## Requirements & limitations
 
-Everything in that bundle that depends on _where_ it runs — binding a port, serving `/_static` and `public/`, reading a prerendered page, gzipping, loading `.env` — sits behind a single interface (`DeployRuntime`) that the build resolves per `deploy` target, so the request-handling code has no platform in it. The entry's default export is whatever the platform expects: nothing where rshono owns the process, a `fetch` handler where the host does.
+- **Node ≥ 22.18** (worker threads, `process.loadEnvFile`, `Promise.withResolvers`, `URL.parse`, and native
+  TypeScript stripping, so a `.ts` config needs no loader) and **React ≥ 19.1** (the floor
+  `react-server-dom-rspack` requires).
+- **ESM only.** The package declares `import` and `types` conditions and no `require` one, so
+  `require('@rshono/core')` is `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than a working call — deliberately,
+  since the framework's own graph is ESM throughout. Use `import`, or `await import()` from CommonJS.
+- No response compression, no base path (`siteUrl` is a bare origin), and wildcard, optional and regex
+  params cannot be prerendered.
+- **No link prefetching**, by choice: a link is one fetch at click time and nothing before it. Speculative
+  fetching on hover spends every visitor's bandwidth to help some of them — so a navigation here costs a
+  round trip that Next.js and TanStack Start have usually already paid.
+- No incremental static regeneration: `render: 'static'` is decided at build time, and a static page changes
+  when you rebuild.
+- **Soft navigation needs the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API)**
+  — Chrome/Edge 135, Firefox 147, Safari 26.2, [Baseline](https://web.dev/blog/baseline-navigation-api) since
+  January 2026. Where it is missing there is no interception at all and every link is a real browser load,
+  which a server-rendered app answers correctly; only the soft part is gone. Scroll restoration, the fragment
+  jump and the post-navigation focus reset are all the browser's.
+- **`redirect()` and `notFound()` must be reached before the page shell is sent.** A page streams: the status
+  line and the first bytes go out as soon as the shell is ready, and HTTP has no take-backs after that. Called
+  from a `<Suspense>` boundary that resolves later, the signal can no longer be a 3xx or a 404 — the response
+  is already committed as `200 text/html`. The signal still rides the payload as a digest, so a browser with
+  JavaScript acts on it: `redirect()` navigates, and `notFound()` — which has nowhere to navigate to — asks
+  for the page once more and then paints a plain "Page not found" panel, since a second identical response is
+  proof that reloading will not help. A visitor without JavaScript is left on the fallback under a 200, and a
+  crawler indexes that 200 as a soft 404. The fix is app-side: decide in Hono
+  middleware, or in the page component body above the boundary. `rshono dev` warns when it happens.
+
+  **On a soft navigation there is no shell to beat, so every `notFound()` degrades.** A flight fetch is
+  committed as `200 text/x-component` the moment the render hands its stream back — before anything has been
+  awaited — so a `notFound()` from the _first line_ of a page component is already too late to be a 404. It
+  rides the payload as a digest, and the client recovers by reloading the page for real (once per URL per
+  tab, then a plain "Page not found" panel). Every in-app click that lands on something missing therefore
+  costs an extra round trip and a full document parse. **`redirect()` is not affected** — the same digest
+  becomes a soft `push()` to the new location, which is what the navigation was going to be anyway. Prefer a
+  `redirect()` where either would do, and decide in Hono middleware where the status still has to be a real 404.
+
+  **A page that _throws_ lands in the same place: the flight response is a `200`.** A document request for it
+  is a 500 answered by your `error` page, but the payload's status was committed before the render failed, so
+  the error rides it as a row and the client runtime paints its error UI — which is the design working, and
+  is what makes a soft navigation onto a broken page recoverable rather than a blank tab. What it costs is
+  observability: **an uptime monitor or a CDN log watching for 5xx sees nothing** for a soft navigation, and
+  the ratio between the two statuses depends on how much of your traffic is in-app clicks. Count failures
+  through `onServerError()`, which fires for both. Buffering the payload to learn whether it failed is the one
+  fix that is not available: it would cost every page its streaming.
+
+- **A page route answers `GET`, `POST` and `HEAD`.** Every other method is a 404 rather than a 405: the
+  `Allow` header a 405 owes the client means tracking the methods registered per path, which is state on a hot
+  path for a distinction nothing acts on differently here. An endpoint route is the way to answer a `PUT`,
+  `PATCH`, `DELETE` or `OPTIONS`.
+- **A page route refuses every cross-site form post**, not only one carrying a server action. A form post to
+  a page is how a `<form action={serverAction}>` reaches the server, and whether a given one holds an action
+  can only be known by reading the body — so the framework refuses on `Sec-Fetch-Site` and the request's
+  shape, before parsing, rather than buffering a body for anyone who asks. "Shape" is all three `enctype`
+  values a browser form can send — `application/x-www-form-urlencoded`, `multipart/form-data` and
+  `text/plain` — since what makes one forgeable from another site is the shape and not what is in it. The
+  cases this rules out are real ones: a **SAML ACS callback**, OIDC **`response_mode=form_post`**, and most
+  payment-gateway returns all arrive as a cross-site POST in exactly that shape. `csrf()`'s allowlist does
+  not widen it — this is the framework declining to run its own action mechanism, ahead of any app policy.
+  **Receive them on an `{ type: 'endpoint' }` route**, which calls your Hono handler directly and never
+  reaches the page renderer, then redirect to the page.
+- **`/_static` is reserved**, on every deploy target and under `rshono dev`: it is where the hashed client
+  bundle is served from, mounted ahead of the route table and answering its whole subtree. A route whose path
+  is `/_static` or sits below it is refused by name — it could never have answered a request. A parameterised
+  route that happens to overlap the prefix (`/:section/thing`) is left alone; it loses those paths and
+  answers the rest.
+- **A page's `ctx` prop is non-enumerable**, so `<Child {...props} />` hands a _server_ child
+  `ctx: undefined` — silently, since a spread copies enumerables only, and the type still says it is there.
+  It cannot be otherwise: an enumerable `ctx` would put `ctx.hono.env`, every binding and secret, into
+  React's dev-only serialization of a server component's props. Nested server components are meant to call
+  `getRequestContext()` rather than be handed the context.
+- **`rshono build` does not type-check.** swc strips types and `tsc` is never invoked, so the build is as fast
+  as it is and no faster because it skipped something. Several of the framework's guarantees are types alone —
+  the `handler` an endpoint module owes, and `defineRoutes`' path ↔ props and `staticPaths` ↔ path checks — so
+  run `tsc --noEmit` (`npm run typecheck` in a scaffolded app) in CI beside the build. The mistakes that make
+  a route unservable are checked at build time whether or not you do.
+- **`.env` and `rshono.config.ts` are read once, at startup**, and what a build needs from them is compiled
+  in — so `rshono dev` does not pick up an edit to either, and a rebuild that serves the old value looks like
+  nothing happened. Restart it; it watches both and says so when one changes.
+- The dev proxy doesn't forward WebSocket upgrades to a custom sub-app; production is unaffected.
+- **`rshono dev` answers `/_static` itself, so your middleware does not run for an asset** — where a build
+  serves assets through the app and they carry HSTS, your CSP and everything else it sets. The dev front-end
+  owns the prefix on purpose: every request it proxies waits on the server rebuild, and the client bundle is
+  built by a separate compiler, so proxying assets would stall the browser's JS and CSS on a save that only
+  touched a server component. The cost is that a policy is developed against files it does not apply to;
+  check a header that has to be on an asset against `rshono build` and `rshono start`.
+- Dev source maps embed the original source of `'use server'` modules (dev binds 127.0.0.1 only, and
+  production ships no client source maps).
 
-## Deployment
-
-`rshono build` targets one platform. Pick it with `deploy` in the config, `--deploy <name>`, or `RSHONO_DEPLOY` (in that precedence order); the default is `node`. `rshono dev` always runs the Node dev server whatever you choose — the target is a property of the build, not of developing.
+## Testing
 
-| `deploy`     | Handoff                          | Assets & prerendered pages                                      | After `build`                                         |
-| ------------ | -------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
-| `node`       | binds a port                     | from `dist/` on disk                                            | `rshono start`                                        |
-| `bun`        | `{ fetch, port }` default export | from `dist/` on disk                                            | `bun dist/server/main.mjs`                            |
-| `deno`       | `{ fetch }` default export       | from `dist/` on disk                                            | `deno serve -A dist/server/main.mjs`                  |
-| `cloudflare` | `{ fetch }` default export       | Workers Assets; prerendered pages read via the `ASSETS` binding | `wrangler deploy`                                     |
-| `vercel`     | web handler in a Node function   | CDN for assets; prerendered pages inside the function           | `vercel deploy --prebuilt`                            |
-| `netlify`    | web handler, Functions v2        | CDN for assets; prerendered pages inside the function           | `netlify deploy --build=false --dir=.netlify/publish` |
-| `aws-lambda` | streaming handler (Function URL) | from the deployment package                                     | zip `dist/`, handler `dist/server/main.mjs`           |
+`pnpm --filter @rshono/core test` builds the package and runs everything that needs no browser:
+
+- **unit** — the parsers and path maths, against the built `dist/`, which also proves the published output
+  loads in plain Node.
+- **production e2e** — builds `apps/testbed`, boots the real production server, and asserts pages, the flight
+  protocol, actions (client and no-JS), CSRF rejection, secret stripping in bundles _and_ rendered HTML, SSG
+  output with `ETag`/304, cache and security headers, and error reporting. The hardened permutations — a
+  nonce CSP, a CSRF allowlist, a small body cap — are middleware, so they run against that same build
+  under a different environment; `trustProxy` is baked in and gets a fixture config.
+- **the other deploy targets** — the `cloudflare` bundle driven as `fetch(request, env, ctx)` against a
+  stand-in `ASSETS` binding, a real build per serverless target checked against the handoff its platform
+  expects, and `rshono start`'s refusal to run a build made for another one.
+- **minimal app**, a fixture with `src/routes.ts` and nothing else (everything the docs call optional, left
+  out); **postcss**, the documented Tailwind wiring actually run; **dev**, a smoke test through the dev
+  server's worker and proxy.
+
+`pnpm --filter @rshono/core test:browser` runs the Playwright suite against a production build: hydration,
+soft navigation, `useNavigation`, client-initiated actions, boundary fallbacks and the fatal overlay — the
+client runtime, which no amount of asserting on HTML can reach.
+
+`test:coverage` gates the build tooling, **not the request hot path** — worth knowing before reading anything
+into the number. Node measures what this process loads, and the modules that answer a request only ever run
+inside the bundled testbed in a child process: `entry.rsc`, `entry.client`, `entry.ssr`, `boundaries`,
+`navigation` and every `deploy/*/runtime` appear nowhere in the report, and `runtime/` in it means `context`,
+`control`, `flight-inject`, `hot-update`, `request` and `validate-entries` alone. Those absent modules are the
+most thoroughly tested code in the package — by the e2e suites above, over HTTP, which is the only way to test
+them at all. So the percentage covers the builder, the CLI, the deploy build steps and the pure runtime
+helpers; treat its floors as a ratchet on those, and never as a statement about the framework as a whole.
+
+The other half can be measured on demand, and is worth a look before a release. Every process the suite
+spawns writes its own V8 coverage if you ask for it, and the testbed's bundle carries a source map that
+reaches back into this package's `src/`, so the request path can be remapped onto the files it came from:
 
-Every target streams: a page's HTML reaches the browser as it renders, which is the whole reason the SSR shell is worth having. That is the bar a new target has to clear.
+```bash
+# from the repository root, so the testbed the coverage points into is under the working directory
+NODE_V8_COVERAGE=.coverage-e2e node --test packages/core/test/prod.test.mjs
+npx c8 report --temp-directory .coverage-e2e --reporter=text --all=false --exclude-after-remap \
+  --exclude='**/node_modules/**' --exclude='**/testbed/src/**' --exclude='**/webpack/**' \
+  --exclude='**/test/**' --exclude='**/drift-*/**' --exclude='**/*.css'
+```
 
-Notes worth knowing before choosing one:
+One suite at a time, because a full run builds the testbed several times over — production, dev, cloudflare,
+vercel — and each bundle is a separate path holding the same sources, which no total can add up. Last taken
+this way, the production e2e suite alone reached **97.4% of `entry.rsc.tsx`** (92.3% of its branches),
+**100% of `entry.ssr.tsx`, `navigation.tsx` and the node runtime**, and 88% of `boundaries.tsx` — the rest of
+which is its client half, and belongs to the browser suite. That is why the gate is left where it is rather
+than tightened: the code it cannot see is not the code that is thin.
 
-- **Cloudflare** bundles all your dependencies (a Worker resolves no `node_modules` at runtime), so a dependency that needs a real `node:` API beyond `nodejs_compat` will not work. The build scaffolds a `wrangler.jsonc` if the project has none — including `nodejs_compat`, which the request context needs for `AsyncLocalStorage` — and never touches it again. Bindings (D1, KV, R2) arrive as `getContext().env`; they are not available under `rshono dev`, which is plain Node.
-- **Prerendered pages are never CDN-served.** One URL answers with an HTML document or a flight payload depending on `Accept`, and a path-keyed CDN cannot choose, so the app always handles page URLs. Assets under `/_static` and `public/` do go straight to the CDN where there is one.
-- **Compression** is left to the platform on `cloudflare`, `vercel` and `netlify`; the framework's streaming gzip is used on `node`, `bun`, `deno` and `aws-lambda`. Your `compress` setting only decides whether an available compressor is used.
-- **AWS** means a Lambda Function URL with the invoke mode set to `RESPONSE_STREAM`, usually with CloudFront in front for `/_static` and `public/`. **Lambda@Edge is deliberately not a target**: CloudFront returns the response as a value rather than a stream, caps a generated origin-request response near 1 MB, and supports no environment variables at all — so `getContext().env` would be empty there, which is a documented feature quietly doing nothing.
-- `rshono start` refuses a build made for another platform rather than starting a bundle with no listener in it.
+## How it works
 
-## Requirements & limitations
+Two coordinated Rspack compilers, using native RSC support (`rspack.experiments.rsc`):
 
-- Node ≥ 22.1 (worker threads, `process.loadEnvFile`, `Promise.withResolvers`, `URL.parse`), React ≥ 19.1 (the floor `react-server-dom-rspack` itself requires).
-- Responses are gzipped, not brotli — one encoding every client accepts, chosen per chunk so streaming survives. Set `compress: false` behind a proxy that does better.
-- Dev-mode proxy doesn't forward WebSocket upgrades to a custom sub-app (prod is unaffected — the bundle owns the socket there).
-- Dev source maps embed the original source of `'use server'` action modules (dev binds to 127.0.0.1 only; production ships no client source maps).
+- **client** (`target: web`) → `dist/static`: hydration runtime, `'use client'` chunks, CSS.
+- **server** (`target: node`) → `dist/server/main.mjs`: a Hono app assembled from your routes, rendered
+  through two layers — the RSC layer, with the `react-server` condition, produces the flight payload; the SSR
+  layer turns it into an HTML stream with the payload inlined for hydration.
+
+In dev the CLI watches both bundles, runs the server bundle in a worker thread (restarted per rebuild,
+requests gated on readiness so nothing drops), and fronts everything on one port with static serving and an
+SSE channel: client edits hot-apply via react-refresh, server component edits re-fetch the payload in place,
+and browser state survives both. In production `dist/server/main.mjs` has React, Hono and the framework
+bundled in. On `node` your server-side dependencies still resolve from `node_modules` beside it; on the
+serverless targets they are bundled too, because nothing installs them there. Whatever a `'use client'`
+component reaches is bundled on every target, which is what lets the env shadow cover it.