@alxia/react-router 0.4.0 → 0.6.0

package/docs/guide.md

@@ -16,7 +16,7 @@ deploying.
 - [The app's own context keys](#the-apps-own-context-keys)
 - [A CSP nonce](#a-csp-nonce)
 - [Escape hatches](#escape-hatches)
-- [Hooks around the pages](#hooks-around-the-pages)
+- [Middlewares around the pages](#middlewares-around-the-pages)
 - [Routes beside the pages](#routes-beside-the-pages)
 - [WebSockets](#websockets)
 - [The client's files](#the-clients-files)
@@ -26,7 +26,35 @@ deploying.
 
 ## Setup
 
-Start from React Router's official template:
+### A new app: `bun create @alxia`
+
+```sh
+bun create @alxia my-app --template react-router
+cd my-app
+bun dev
+```
+
+[`@alxia/create`](https://www.npmjs.com/package/@alxia/create) copies React
+Router's official template with alxia's layer already applied: the steps
+of the next section, done.
+
+- `@alxia/core` and `@alxia/react-router` installed, and every dependency
+  moved to the newest release alxia accepts (see
+  [`@alxia/create`'s Versions](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#versions));
+- `alxia()` in `vite.config.ts`, the `bunfig.toml`, and `start` running
+  `NODE_ENV=production bun build/server/index.js`;
+- Biome, with `lint`, `format`, `check`, `check:ci` and `verify` scripts;
+- a `Dockerfile` that builds on `oven/bun:1` and runs `build/` alone on
+  `oven/bun:1-alpine`, as [Deploying](#deploying) describes.
+
+`bun run verify` checks, typechecks and builds it.
+[`@alxia/create`'s guide](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#running-it)
+lists the command's options. The template keeps `@react-router/serve` in its
+dependencies, unused: remove it if you like.
+
+### An existing React Router app
+
+Start from React Router's official template, or your own app:
 
 ```sh
 bunx create-react-router@latest my-app
@@ -68,7 +96,7 @@ middleware must come after alxia's.
 "scripts": {
 	"build": "react-router build",
 	"dev": "react-router dev",
-	"start": "bun build/server/index.js",
+	"start": "NODE_ENV=production bun build/server/index.js",
 	"typecheck": "react-router typegen && tsc"
 }
 ```
@@ -96,9 +124,10 @@ What the template keeps:
 - `@react-router/node`, which React Router's default `entry.server`
   renders with: it streams under Bun.
 - Vite 7 or 8 (the template ships 8).
-- Its `typescript` 5.9. This package's peer asks for 6 or 7, so `bun add`
-  warns, but the template's code typechecks with 5.9.
-  `bun add -d typescript@^6` silences the warning.
+- With `bunx create-react-router`, its `typescript` 5.9. This package's
+  peer asks for 6 or 7, so `bun add` warns, but the template's code
+  typechecks with 5.9. `bun add -d typescript@^6` silences the warning;
+  `bun create @alxia` writes 6 or 7 already.
 
 React Router 8 is required: its loaders receive a `RouterContextProvider`,
 and alxia's context is set on it.
@@ -144,13 +173,21 @@ server build inside it, into one file:
   stay out of it.
 - **Run, it listens**: `bun build/server/index.js` listens on `PORT`
   (3000 by default) and `HOST` (`0.0.0.0`). It prints
-  `alxia listening on <url>`. On `SIGINT` or `SIGTERM` it stops the app,
-  runs its `onStop` hooks, and exits.
+  `alxia listening on <url>`, and in dev — under `react-router dev`; a
+  production build never is, whatever `NODE_ENV` says — the route table
+  ([`@alxia/core`'s Development](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/development.md#the-route-table)). On `SIGINT` or `SIGTERM` it shuts the app
+  down as `@alxia/core`'s `listen` does: readiness turns 503, new
+  connections are refused, the requests in flight finish within
+  `shutdownTimeout` (10 s; `listen: { shutdownTimeout }` sets it), the
+  `onStop` hooks run, and the process exits
+  ([core's guide](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/health-and-shutdown.md)).
 - **Imported, it starts nothing**: prerendering, a test or another server
   can import it safely, since it listens only when it is the process's
   entry point (`import.meta.main`).
 - **The mode follows the command**: `development` under `react-router dev`,
-  `production` in a build, whatever `NODE_ENV` says.
+  `production` in a build, whatever `NODE_ENV` says. The app's dev switch
+  follows it: `alxia({ dev: mode === 'development' })`, so a 500 of the
+  build never shows its stack.
 - **The client folder is resolved against the built file**: `../client`,
   from React Router's `buildDirectory`, so it is found wherever the
   process starts.
@@ -188,7 +225,7 @@ The plugin loads `build/server/index.js` on the first request and hands
 every request to its default export, the alxia app, before Vite's own
 files. So the preview answers as `bun run start` does: the pages and their
 data, `/api`, `build/client` with the cache headers of
-[the client's files](#the-clients-files), and every hook of `beforeAll`
+[the client's files](#the-clients-files), and every middleware of `beforeAll`
 and `configure`. Requests, their bodies and every `Set-Cookie` pass
 through whole, and pages stream.
 
@@ -212,7 +249,7 @@ React Router prerenders the `prerender` paths of `react-router.config.ts`
 through the same preview server, during `react-router build`. A
 prerendered page is therefore rendered by the built server too: its loader
 reads `alxiaOf(context)` and `getLoadContext`'s keys, and `beforeAll`'s
-and `configure`'s hooks run around it.
+and `configure`'s middlewares run around it.
 
 ## Built for Bun
 
@@ -368,7 +405,7 @@ bunx alxia-react-router reveal
 
 ```text
 alxia-react-router: wrote app/server.ts, the server alxia() runs by default.
-Next: uncomment configure in app/server.ts to add the app's hooks and /api; bun run dev picks it up.
+Next: uncomment configure in app/server.ts to add the app's middlewares and /api; bun run dev picks it up.
 ```
 
 The file is the server the plugin runs without one, `createServer()`, so
@@ -427,7 +464,7 @@ React Router's own rendering entries, `app/entry.server.tsx` and
 ### By hand
 
 The example uses `@alxia/logger` and `@alxia/compress`
-(`bun add @alxia/logger @alxia/compress`); any plugin works the same way.
+(`bun add @alxia/logger @alxia/compress`); any middleware works the same way.
 
 ```ts
 // app/server.ts
@@ -460,12 +497,12 @@ Every option is optional:
 
 | option | what it does |
 | --- | --- |
-| `configure(app)` | the app the pages run behind: its plugins, hooks and `/api`. It returns the app, and what it builds is what the loaders read |
+| `configure(app)` | the app the pages run behind: its middlewares and `/api`. It returns the app, and what it builds is what the loaders read |
 | `beforeAll(app)` | runs first, on a new app. What it declares applies to the client's files too: a rate limit, a guard on everything, a logger that should see every asset. It returns the app, which `configure` then receives |
 | `getLoadContext(ctx, context)` | sets the app's own keys on React Router's provider, `ctx` typed by `configure`'s app |
 | `build`, `mode`, `client` | override what the plugin wires; see [Escape hatches](#escape-hatches) |
-| `listen` | `listen`'s options for `bun build/server/index.js`: `port`, `hostname`, `idleTimeout`, `maxRequestBodySize`, `tls`. A `port` or `hostname` given here wins over `PORT` and `HOST` |
-| `onListen(server)` | called once the built server listens and its `SIGINT` and `SIGTERM` handlers are in place, in place of the `alxia listening on …` line; a signal sent from then on runs the `onStop` hooks |
+| `listen` | `listen`'s options for `bun build/server/index.js`: `port`, `hostname`, `idleTimeout`, `maxRequestBodySize`, `tls`, `onListen`. A `port` or `hostname` given here wins over `PORT` and `HOST`; an `onListen` here, told `@alxia/core`'s `ListenInfo` — `url`, `routes`, `table`, `dev` — wins over the option below |
+| `onListen(server)` | called once the built server listens and its `SIGINT` and `SIGTERM` handlers are in place, in place of the `alxia listening on …` line (and, in dev, of the route table); a signal sent from then on runs the `onStop` hooks |
 
 A request goes through four layers, in order:
 
@@ -474,11 +511,16 @@ A request goes through four layers, in order:
 3. what `configure` declared;
 4. the pages: `GET`, `POST`, `PUT`, `PATCH` and `DELETE` at `/*`.
 
-Hooks apply to the routes declared after them, so a session or a guard in
-`configure` runs around every page and its data, but not around the
-JavaScript of the login page. Global hooks (`onRequest`, `@alxia/cors`,
-`@alxia/compress`, `@alxia/secure-headers`) apply everywhere, wherever
-they are declared.
+A middleware given to `use` runs on every route declared after it, and on a
+request no route matches. So a session or a guard in `configure` runs around
+every page and its data, and not around what is declared before it: the
+client's files, which sit between `beforeAll` and `configure`. What must see
+every request, the client's files included, goes in `beforeAll`: the logger,
+`@alxia/cors`, `@alxia/compress`, `@alxia/secure-headers`. A guard on the app
+answers a request no route matches too: an anonymous request to a missing path
+gets the 401, not the 404. Scope it with a path, `use('/app', guard)`
+(a guard that adds nothing to the context: `bearer` and `session` add `user`),
+to guard only some pages.
 
 ```ts
 // app/server.ts: a guard on everything, the assets included
@@ -495,13 +537,13 @@ export default createServer({
 ```
 
 `configure` and `beforeAll` must return the app; one that returns nothing
-is a compile error. A plugin that needs something an earlier one
+is a compile error. A middleware that needs something an earlier one
 derived is typed by the app it is given, as anywhere in alxia.
 
 ## Typing the loaders
 
 Every request through the catch-all sets `alxiaContext`, this package's
-key, on React Router's context provider, to what alxia's hooks built for
+key, on React Router's context provider, to what alxia's middlewares built for
 that request. `alxiaOf(context)` reads it.
 
 ### With `Register`: no type argument
@@ -546,7 +588,7 @@ shows. The checks it gives:
 
 ```ts
 const ctx = alxiaOf(context);
-ctx.tenant;     // error: no hook derives `tenant`
+ctx.tenant;     // error: no middleware derives `tenant`
 ctx.user.name;  // error: `user` may be null
 ```
 
@@ -577,19 +619,57 @@ export function loader({ context }: Route.LoaderArgs) {
 
 The type argument may also be an alxia app, the app *before* the
 catch-all, for a server of your own. Anything else is a compile error.
-With neither `Register` nor a type argument, `alxiaOf(context)` is
-`BaseContext`: the request, its URL, `reply` and the rest of what every
-hook reads.
+
+### With `@alxia/core`'s `Register`
+
+`@alxia/core` has a `Register` of its own, which names the chain that
+builds an app's context, for its route files
+([The app's type](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/types.md#register-and-appcontext)).
+`alxiaOf(context)` reads it when this package's `Register` names no
+server:
+
+```ts
+// app/context.ts
+import { alxia } from '@alxia/core';
+
+export const base = alxia().derive(({ request }) => ({ user: request.headers.get('x-user') }));
+
+declare module '@alxia/core' {
+	interface Register {
+		context: typeof base;
+	}
+}
+
+// app/server.ts
+const server = createServer({ configure: (app) => app.plugin(base) });
+export default server;
+```
+
+`alxiaOf(context).user` is then typed with no declaration in
+`@alxia/react-router`. Which one is read, in order:
+
+1. a type argument, `alxiaOf<typeof server>(context)`;
+2. this package's `Register`, `server: typeof server`: the whole app the
+   pages run behind, `base` and everything `configure` adds after it;
+3. `@alxia/core`'s `Register`, `context: typeof base`: only what `base`
+   builds;
+4. neither: `BaseContext`, the request, its URL, `reply` and the rest of
+   what every middleware reads.
+
+Declare this package's `Register` when `configure` adds to the context
+after the base, and the loaders read it.
 
 ### Why a global augmentation is right here
 
-alxia's core refuses global augmentation of its context: a plugin that
-added `user` to every route, declared before it or after, would type
-`user` on routes that run before the plugin. That is the lie "order is
-meaning" forbids. `Register` here does something else: it names the
-**one** server of the React Router build, at the point of its catch-all,
-which is exactly what every loader runs behind. One build has one server
-entry, so there is no second app for a module to be confused with.
+alxia's core refuses a global augmentation of a context key: a plugin
+that added `user` to every route, declared before it or after, would
+type `user` on routes that run before the plugin. That is the lie "order
+is meaning" forbids. Core's own `Register` names the base that builds
+the context instead, and what reads it requires it. `Register` here does
+something else: it names the **one** server of the React Router build,
+at the point of its catch-all, which is exactly what every loader runs
+behind. One build has one server entry, so there is no second app for a
+module to be confused with.
 
 If two React Router apps share one TypeScript program (one tsconfig over
 both folders of a monorepo), their two declarations conflict, and `tsc`
@@ -639,7 +719,7 @@ export function loader({ context }: Route.LoaderArgs) {
 
 `getLoadContext` runs before React Router, on every request, with
 `alxiaContext` already set. Its `ctx` is typed by `configure`'s app:
-reading something no hook derives is a compile error. Keep the keys in a
+reading something no middleware derives is a compile error. Keep the keys in a
 module of their own, such as `app/context.ts`, rather than in
 `app/server.ts`: a route imports them, and the server file then stays out
 of the client's module graph.
@@ -729,7 +809,7 @@ scripts included.
 ### How it stays loose
 
 `nonceOf` reads `nonce` from alxia's context if it is a string, and
-returns `undefined` otherwise: no hook set one, or the request did not come
+returns `undefined` otherwise: no middleware set one, or the request did not come
 through alxia at all. `ServerRouter` and React then render no `nonce`
 attribute. So:
 
@@ -816,7 +896,7 @@ export const base = alxia()
 /** What the loaders read: alxiaOf<Base>(context). */
 export type Base = typeof base;
 
-const app = base.use((app) =>
+const app = base.plugin((app) =>
 	reactRouter(app, {
 		build: () =>
 			import(new URL('./build/server/index.js', import.meta.url).href) as Promise<ServerBuild>,
@@ -838,7 +918,7 @@ bun run build && bun server.ts
 | `getLoadContext(ctx, context)` | as `createServer`'s |
 | `client` | the client build's folder, a path or a `file:` URL, served before the catch-all in `production` |
 
-`reactRouter()` goes through `use`, as `@alxia/graphql`'s `graphql(app, …)`
+`reactRouter()` goes through `app.plugin`, as `@alxia/graphql`'s `graphql(app, …)`
 does: that is how it knows the app's context type. A `HEAD` is handed to
 React Router as a `GET`, since React Router answers a `HEAD` of its own
 with no headers at all; the core then drops the body. In a monorepo where
@@ -846,14 +926,15 @@ this package is linked rather than installed, add
 `ssr: { external: ['@alxia/react-router'] }` to `vite.config.ts`: see
 [the troubleshooting entry](troubleshooting.md#alxiaof-this-request-has-no-alxia-context-).
 
-## Hooks around the pages
+## Middlewares around the pages
 
-Every hook declared before the catch-all runs around each page, as around
-any route:
+Every middleware declared before the catch-all runs around each page, as around
+any route, and `use` observers go first so they wrap everything:
 
 - **`@alxia/logger`** writes one entry per request and sets
   `x-request-id`. It times a streamed page by its first byte, since
-  `onResponse` runs when the headers leave.
+  the response is settled when its headers leave. Every request is logged,
+  404s and errors included.
 - **`@alxia/compress`** compresses documents and data, and flushes a
   streamed page as React writes it: the shell and its `<Suspense>`
   fallback still arrive first, in zstd, Brotli or gzip. See [the troubleshooting entry](troubleshooting.md#a-streamed-page-arrives-in-one-piece).
@@ -865,7 +946,8 @@ any route:
   [A CSP nonce](#a-csp-nonce).
 - **A guard** — `@alxia/jwt`'s `bearer`, `@alxia/janus`' session — in
   `configure` guards every page and its data alike; in `beforeAll`, the
-  client's files too.
+  client's files too. On the app, a guard also answers a request no route
+  matches with its 401.
 
 ## Routes beside the pages
 
@@ -883,7 +965,7 @@ export default createServer({
 });
 ```
 
-Each answers with its own schemas, replies and typed client. The core ranks
+Each answers with its own middlewares and replies. The core ranks
 paths as `Bun.serve` does, through `listen`, `app.fetch` and
 `app.request` alike: segment by segment, a literal beats a parameter,
 which beats the catch-all's wildcard. Two consequences:
@@ -894,10 +976,10 @@ which beats the catch-all's wildcard. Two consequences:
   every one-segment path, `/about` included, before React Router sees it.
   Put alxia's routes under a prefix of their own, `/api`.
 
-The catch-all adds nothing to the app's route table: `RoutesOf` and the
-typed client never show `/*`. Pages and single-fetch data are not
-something a typed client calls; what it does call, your `/api`, is typed
-as always.
+Pages and single-fetch data are not something a generated client calls:
+leave the catch-all out of `matchesSpec`'s check with `isReactRouterRoute`
+([OpenAPI](#openapi)); what a client does call, your `/api`, is what the
+OpenAPI document declares.
 
 What React Router answers comes back as it sent it: documents,
 single-fetch data (`/_.data`, `/login.data`), lazy route discovery
@@ -943,10 +1025,10 @@ export default createServer({
 });
 ```
 
-The upgrade runs the hooks declared before the route, and the route's
-validation, as any request does. A hook's reply refuses it: the client
+The upgrade runs the middlewares declared before the route, and the route's
+validation, as any request does. A middleware's reply refuses it: the client
 gets the 401 and its body, and no socket opens. `socket.data` holds the
-validated request and what each hook derived, typed. See
+validated request and what each middleware derived, typed. See
 [`@alxia/core`'s WebSockets](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/websockets.md)
 for the schemas and the rest of the socket.
 
@@ -966,7 +1048,7 @@ byte for byte, to a `Bun.serve` of the app on a loopback port of its
 own, started on the first upgrade and given
 `app.fetch` and `app.websocket`, as `listen` gives them. So in dev:
 
-- **The same hooks, refusals and handlers run** as from the build:
+- **The same middlewares, refusals and handlers run** as from the build:
   `open`, `message`, `close`, `drain`, the `message` and `send` schemas,
   `subscribe` and `publish`.
 - **An edit to `app/server.ts`, or to a module it imports, is used from
@@ -1016,25 +1098,49 @@ refused when the server starts: see
 
 ## OpenAPI
 
-`@alxia/openapi` documents every route of `app.routes`, and the catch-all
-and the client's files are routes. Leave them out with
+alxia is OpenAPI spec first: the document is written by hand, the API's
+routes are bound to the operations generated from it, and
+[`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi)'s
+`matchesSpec` checks, in a test, that `app.routes` and the operations
+match both ways. The catch-all and the client's files are routes of
+`app.routes`, and no operation of the document. Leave them out with
 `isReactRouterRoute`, which is true for each route this package declared:
 
 ```ts
 // app/server.ts
-import { docs } from '@alxia/openapi';
-import { createServer, isReactRouterRoute } from '@alxia/react-router';
+import { createServer } from '@alxia/react-router';
+import { operations } from './generated/alxia';
 
 export default createServer({
 	configure: (app) =>
 		app
 			.get('/api/health', ({ reply }) => reply.ok({ ok: true }))
-			.use(docs(app, { info: { title: 'Shop', version: '1.0.0' }, exclude: isReactRouterRoute })),
+			.route(operations.listOrders, ({ reply }) => reply.ok([])),
+});
+```
+
+```ts
+// app/server.test.ts
+import { test } from 'bun:test';
+import { matchesSpec } from '@alxia/openapi';
+import { isReactRouterRoute } from '@alxia/react-router';
+import type { ServerBuild } from 'react-router';
+import { operations } from './generated/alxia';
+import server from './server';
+
+test('the API routes every operation of openapi.yaml, and nothing else', async () => {
+	const build: ServerBuild = await import(new URL('../build/server/index.js', import.meta.url).href);
+	const app = server.create({ build });
+	matchesSpec(app, operations, {
+		exclude: (route) => isReactRouterRoute(route) || route.path === '/api/health',
+	});
 });
 ```
 
-Combine it with your own: `exclude: (route) => isReactRouterRoute(route) ||
-route.path === '/api/health'`.
+When the app puts the operations under a prefix the document's paths
+leave out, `app.group('/api', (api) => api.route(…))`, give `matchesSpec`
+the same `prefix: '/api'`. See
+[`@alxia/openapi`'s checks](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/checks.md).
 
 ## Testing
 
@@ -1083,7 +1189,8 @@ no `node_modules`, unless the app keeps a package external with
 The `react-router` template of
 [`@alxia/create`](https://github.com/softistx/alxia/tree/develop/packages/create)
 and the [example](https://github.com/softistx/alxia/tree/develop/examples/react-router)
-ship this `Dockerfile`, on Bun's official image. For an app started from
+ship this `Dockerfile`, on Bun's official images: built on `oven/bun:1`,
+Debian's, and run on `oven/bun:1-alpine`, about 130 MB. For an app started from
 `create-react-router`, it replaces the template's, which builds and runs
 on Node:
 
@@ -1106,8 +1213,10 @@ RUN bun run build
 # command, and --no-install: with no node_modules, Bun would otherwise
 # fetch a package the build left out from the registry at startup,
 # where this fails.
-# The server listens on PORT (3000) and HOST (0.0.0.0).
-FROM oven/bun:1
+# The server listens on PORT (3000) and HOST (0.0.0.0). On Alpine, about
+# 200 MB lighter: build/ is JavaScript, which runs the same on musl. A
+# native addon built for glibc alone needs oven/bun:1 here.
+FROM oven/bun:1-alpine
 WORKDIR /app
 ENV NODE_ENV=production
 COPY --from=build /app/build ./build
@@ -1133,6 +1242,11 @@ startup, where Bun would otherwise fetch it from npm.
   gets the versions you tested, and a `package.json` changed without a
   `bun install` fails the build
   ([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#error-lockfile-had-changes-but-lockfile-is-frozen)).
+- **The final stage is Alpine's**, musl where the build stage has glibc.
+  `build/` is JavaScript, which runs the same on both. A native addon
+  kept external and built for glibc alone does not load there: put the
+  final stage back on `oven/bun:1`
+  ([`@alxia/create`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)).
 - **The server runs as `bun`**, a user with no write access to `/app`.
   Write files to a volume the user owns
   ([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#eacces-permission-denied-open-app)).
@@ -1157,5 +1271,6 @@ startup, where Bun would otherwise fetch it from npm.
   ([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#error-cannot-find-package--from-appbuildserverindexjs)).
 
 `PORT` and `HOST` set where the server listens. The platform's `SIGTERM`
-stops it once the requests in flight are answered, and runs the app's
-`onStop` hooks.
+stops it once the requests in flight are answered, within
+`shutdownTimeout`, and runs the app's `onStop` hooks. Give the platform a
+readiness probe with `@alxia/core`'s `health()`, mounted in `beforeAll`.

package/docs/roadmap.md

@@ -7,7 +7,20 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing scheduled yet.
+- **Middlewares around the pages.** `beforeAll` and `configure` take
+  `use(logger())`, `use(secureHeaders())` and the other middlewares of
+  alxia 0.4, which run on the pages, the client's files declared after
+  them, and every request no route matches; the request hooks they replaced,
+  deprecated in 0.4, were removed in 0.5.
+- **Loaders typed by core's `Register`.** `alxiaOf(context)` reads the base
+  `@alxia/core`'s `Register` names when this package's names no server, so
+  an app that registers its context once types its loaders too. This
+  package's `Register` still wins when both are declared.
+- **One graceful shutdown.** `start` relies on `@alxia/core`'s `listen`,
+  which handles `SIGINT` and `SIGTERM` itself, before `onListen` as
+  before: the requests in flight drain within `shutdownTimeout`
+  (`listen: { shutdownTimeout }`), readiness turns 503, the `onStop`
+  hooks run, then the process exits.
 
 ## Next
 
@@ -29,9 +42,9 @@ Nothing scheduled yet.
   only behind `future.v8_middleware`, and the line is in maintenance.
 - **Node or Cloudflare.** alxia is a Bun framework; React Router's own
   adapters serve those runtimes.
-- **The pages in the route table.** Documents and single-fetch data are not
-  something the typed client calls, so the catch-all stays out of
-  `RoutesOf`.
+- **The pages in the OpenAPI document.** Documents and single-fetch data
+  are not something a generated client calls, so `isReactRouterRoute`
+  leaves the catch-all out of `matchesSpec`'s check.
 - **A runtime dependency.** The package declares none: `@alxia/core` and
   `react-router` are peers.
 - **A `react-router-serve` of its own.** `bun build/server/index.js` is the
@@ -45,23 +58,28 @@ Nothing scheduled yet.
 
 ## Shipped
 
-### Next release
+### 0.4.0
 
 - **A self-contained build.** `react-router build` bundles every package
   into `build/server/index.js`, React, React Router and alxia included,
   so `build/` runs with no `node_modules` and a Docker image copies it
   alone. Never in dev; `ssr.external` keeps a package external, and
   `ssr.external: true` every package.
+
+### 0.3.0
+
 - **The server is built for Bun.** `alxia()` adds the `bun` export
   condition to the `ssr` environment's conditions and external
   conditions, keeps `bun` and `bun:*` external whichever runtime runs
   Vite, and targets `esnext`, in dev and in the build, with nothing to
   configure. A package's `bun` variant is the one bundled, and what the
   app sets is kept.
-- **A Docker image on Bun.** The guide's Deploying has the multi-stage
-  `Dockerfile` on `oven/bun:1` that `@alxia/create`'s template and the
-  example ship, running `bun build/server/index.js` as a non-root user,
-  from `build/` alone.
+- **A Docker image on Bun.** The guide's Deploying has a multi-stage
+  `Dockerfile` on `oven/bun:1`, running `bun build/server/index.js` as a
+  non-root user.
+
+### 0.2.0
+
 - **A per-request CSP nonce.** `nonceOf(loadContext)` reads the nonce that
   `@alxia/secure-headers`' `nonce: true`, or a `derive` of the app's own,
   put on the context, so `entry.server.tsx` hands it to `<ServerRouter
@@ -73,9 +91,9 @@ Nothing scheduled yet.
 
 - **React Router as a catch-all.** `reactRouter(app, { build })` serves
   documents, single-fetch data, actions, redirects with every cookie, lazy
-  route discovery and the error pages, behind every hook declared before
-  it, streamed as React renders them.
-- **The context, typed.** `alxiaOf<App>(context)` reads what alxia's hooks
+  route discovery and the error pages, behind every middleware declared
+  before it, streamed as React renders them.
+- **The context, typed.** `alxiaOf<App>(context)` reads what alxia's middlewares
   built in any loader, action or middleware, through a key that is one
   object however the server was built; `getLoadContext` sets the app's own
   keys.
@@ -85,7 +103,8 @@ Nothing scheduled yet.
 - **`HEAD` with headers.** A `HEAD` is answered as its `GET`, less the
   body.
 - **OpenAPI.** `isReactRouterRoute` leaves the catch-all and the client's
-  files out of `@alxia/openapi`'s document.
+  files out of a check of `app.routes` against the document, such as
+  `@alxia/openapi`'s `matchesSpec`.
 - **Zero config, with Vite.** `@alxia/react-router/vite`'s `alxia()`,
   anywhere in `plugins`, is all an app from the official template needs.
   Without `app/server.ts` a default server serves the pages; with it,
@@ -99,7 +118,7 @@ Nothing scheduled yet.
 - **`vite preview` serves the built server.** After `react-router build`,
   `bunx --bun vite preview` hands every request to `build/server/index.js`,
   as `bun run start` would answer it: the pages, `/api`, the client's files
-  and the app's hooks. React Router's prerendering runs on the same
+  and the app's middlewares. React Router's prerendering runs on the same
   server, so a prerendered page's loader reads `alxiaOf`.
 - **`bunx alxia-react-router reveal`.** The package's bin writes the
   default server into the app, `app/server.ts` or `alxia({ entry })`'s
@@ -110,7 +129,7 @@ Nothing scheduled yet.
 - **WebSockets in dev and preview.** An alxia `ws` route connects under
   `react-router dev` and `vite preview` as from the build, with nothing to
   configure: the plugin relays each upgrade Vite does not claim (HMR, its
-  proxy) to a `Bun.serve` of the app, so its hooks, refusals,
+  proxy) to a `Bun.serve` of the app, so its middlewares, refusals,
   `socket.data` and handlers run as `listen` runs them, and in dev an edit
   to the server is used from the next connection.
 - **Loaders typed with no type argument.** A `Register` declaration beside