react-router-effect 2.1.0 → 2.3.0

package/README.md

@@ -1,7 +1,7 @@
 # react-router-effect
 
 Serve a [React Router](https://reactrouter.com) framework-mode app from [Effect](https://effect.website)'s
-Node HTTP server, and write its loaders, actions and middleware as Effects.
+HTTP router, on Node or on Cloudflare Workers. Write its loaders, actions and middleware as Effects.
 
 A route function that returns an `Effect` runs with your app's services. When it fails with a tagged
 error, the route factory you configure once decides what happens: recover with data for
@@ -24,17 +24,21 @@ If your app does not serve React Router from an Effect HTTP server, read
 
 ## Install
 
+On Node:
+
 ```bash
-vp add react-router-effect effect @effect/platform-node
+vp add react-router-effect effect react-router @effect/platform-node
 ```
 
-`effect`, `@effect/platform-node` and `react-router` are peer dependencies. The library requires
-Effect 4.1 (`effect@^4.1.0`). Only `react-router-effect/vite` imports `@effect/platform-node`.
+`effect`, `react-router` and `@effect/platform-node` are peer dependencies. The library requires
+Effect 4.1 (`effect@^4.1.0`) and Node 22 or later. Only `react-router-effect/vite` imports
+`@effect/platform-node`, so another platform does not need it. The README of each example lists the
+packages of its platform. Read [Platforms](#platforms).
 
 ## Get started
 
-[`examples/basic`](examples/basic) is an app with these files. It also has development with
-Vite, tests against the production build, and benchmarks.
+These steps serve an app on Node in production. [`examples/node`](examples/node) is an app with
+these files. It also has development with Vite, tests against the production build, and benchmarks.
 
 ### 1. Create the route factory
 
@@ -65,51 +69,59 @@ export const { Respond } = routeFactory;
 
 ### 2. Create the server app
 
-`ReactRouterHttp.make` returns an Effect that makes an Effect HTTP app. The app runs React Router
-with your route factory.
+`App` is a layer of routes on Effect's `HttpRouter`. `ReactRouter.layer` loads the build with your
+route factory. `ReactRouter.routes` registers React Router as the catch-all route.
+`ReactRouterAssets.layer` registers the files of the client build. Your own routes and middleware go
+in the same `Layer.mergeAll`.
 
 ```ts
 // server/app.ts
-import { ReactRouterHttp } from "react-router-effect/server";
+import { Layer } from "effect";
+import { ReactRouter, ReactRouterAssets } from "react-router-effect/server";
 
 import { routeFactory } from "../app/lib/route-factory.server";
 
-export const reactRouterApp = ReactRouterHttp.make({
-  build: () => import("virtual:react-router/server-build"),
-  factory: routeFactory,
-  clientAssets: true, // serves build/client in production
-});
+export const App = Layer.mergeAll(ReactRouter.routes, ReactRouterAssets.layer).pipe(
+  Layer.provide(
+    ReactRouter.layer({
+      build: () => import("virtual:react-router/server-build"),
+      factory: routeFactory,
+      mode: import.meta.env.MODE,
+    }),
+  ),
+);
 ```
 
 ### 3. Serve it
 
-The server makes the app once, when it starts, and serves it with its own Effect HTTP server and its
-own middleware. In production, making the app loads the build and reads the client build. If the
-server cannot read the client build, it fails to start, and the error names the resolved directory.
+`server.js` serves `App` with `HttpRouter.serve`, which also logs each request. When the server
+starts, `App` loads the build and reads the client build. If the server cannot read the client
+build, it fails to start with a `ClientBuildError` that names the resolved directory.
 
-```ts
-// server/main.ts
+```js
+// server.js
 import { createServer } from "node:http";
 
-import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
-import { Effect, Layer } from "effect";
-import { HttpMiddleware, HttpServer } from "effect/http";
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import { Layer } from "effect";
+import { HttpRouter } from "effect/http";
 
-import { reactRouterApp } from "./app";
+import { App } from "./build/server/index.js";
 
-Layer.unwrap(
-  Effect.map(reactRouterApp, (app) => HttpServer.serve(app, HttpMiddleware.logger)),
-).pipe(
-  Layer.provide(NodeHttpServer.layer(() => createServer(), { port: 3000 })),
-  Layer.launch,
-  NodeRuntime.runMain,
+NodeRuntime.runMain(
+  Layer.launch(
+    HttpRouter.serve(App).pipe(
+      Layer.provide(NodeHttpServer.layer(() => createServer(), { port: 3000 })),
+    ),
+  ),
 );
 ```
 
 ### 4. Build the server
 
-Make `server/main.ts` the entry of the server build. The build then contains your server, and
-`react-router build` writes it to `build/server/index.js`.
+Make `server/app.ts` the entry of the server build. `react-router build` then writes `App` to
+`build/server/index.js`.
 
 ```ts
 // vite.config.ts
@@ -118,16 +130,17 @@ import { defineConfig } from "vite";
 
 export default defineConfig({
   plugins: [reactRouter()],
-  environments: { ssr: { build: { rollupOptions: { input: "./server/main.ts" } } } },
+  environments: { ssr: { build: { rollupOptions: { input: "./server/app.ts" } } } },
 });
 ```
 
 ```bash
 react-router build
-NODE_ENV=production node build/server/index.js
+NODE_ENV=production node server.js   # React's server build reads NODE_ENV
 ```
 
-For development, read [Development with Vite](#development-with-vite).
+For development with Vite, the Node example's `server.js` serves the app through
+`ReactRouterVite.layer`. Read [Development with Vite](examples/node/README.md#development-with-vite).
 
 ### 5. Write routes as Effects
 
@@ -164,6 +177,28 @@ middleware](#plain-effect-loaders-actions-and-middleware) explains why. A route
 not return an Effect passes through to React Router unchanged, so promise loaders keep working in
 the same app.
 
+## Platforms
+
+`App` is the same layer on every platform. Only the file that serves it changes. Effect has two
+functions that serve it:
+
+- `HttpRouter.serve(App)` with a server layer, such as `NodeHttpServer.layer` on Node.
+- `HttpRouter.toWebHandler(App)`, which returns a fetch handler, such as a Cloudflare Worker's.
+
+| Platform           | Example                                      | Serves `App` with                             |
+| ------------------ | -------------------------------------------- | --------------------------------------------- |
+| Node               | [`examples/node`](examples/node)             | `HttpRouter.serve` and `NodeHttpServer.layer` |
+| Cloudflare Workers | [`examples/cloudflare`](examples/cloudflare) | `HttpRouter.toWebHandler`                     |
+
+The README of each example has the details of its platform. These rules apply on every platform:
+
+- App-wide services go in the route factory's `runtime`. Read
+  [App-wide services with a runtime](#app-wide-services-with-a-runtime).
+- Per-request services go in a router middleware. Read [Per-request services](#per-request-services).
+- A platform service, such as a tracer, goes where the serve function reads it. `HttpRouter.serve`
+  reads the services that `Layer.provide` gives to its layer. `HttpRouter.toWebHandler` reads the
+  services that `Layer.provideMerge` adds to the layer that it gets.
+
 ## Handle errors
 
 An Effect can short-circuit in three ways, with the `Respond` helpers:
@@ -224,6 +259,79 @@ service-specific error that is not a declared domain error. Catch it or map it.
 defaults for declared errors. The errors of one feature or service need explicit handling.
 [The route check](#the-route-check) reports an unhandled error at compile time.
 
+## Defer data
+
+The route factory returns `defer`. It starts an Effect without waiting for it, and gives a promise
+of the result. Put the promise in the loader data. React Router streams it to `<Await>` after the
+first response. `defer` is unstable: a minor version can change it.
+
+```tsx
+// app/lib/route-factory.server.ts
+export const { Respond, defer } = routeFactory;
+
+// app/routes/product.tsx
+export const loader = Effect.fn("loader.product")(function* ({
+  params,
+}: EffectRouteArgs<Route.LoaderArgs>) {
+  const product = yield* (yield* Products).get(params.id);
+  return {
+    product,
+    reviews: yield* defer((yield* Reviews).list(params.id)),
+    stats: yield* (yield* Stats).load(params.id).pipe(
+      Effect.catchTag("StatsUnavailable", () => Effect.succeed(null)),
+      defer,
+    ),
+  };
+});
+
+export default function Product({ loaderData }: Route.ComponentProps) {
+  return (
+    <Suspense fallback={<p>Loading reviews</p>}>
+      <Await resolve={loaderData.reviews} errorElement={<ReviewsError />}>
+        {(reviews) => <ReviewList reviews={reviews} />}
+      </Await>
+    </Suspense>
+  );
+}
+```
+
+The loader yields `defer`, and the deferred work starts at that point. The work and the rest of the
+loader run at the same time. The work gets the services and the span of the loader, so its spans are in the trace of the request. It
+keeps running after the loader returns. The work stops in two cases:
+
+- The request aborts, for example because the client disconnects.
+- The loader fails after it deferred the work. The response then has no data that waits for it.
+
+A client-side navigation to another page does not abort the request. React Router aborts the request
+of a navigation only while its loaders run. The work then runs until it ends, or until React
+Router's `streamTimeout` ends the stream.
+
+The response starts before the deferred work fails, so a failure cannot redirect or change the
+response. The error handlers of the factory turn a failure into a value or a rejection:
+
+| Failure of the deferred Effect                                  | The promise                                       |
+| --------------------------------------------------------------- | ------------------------------------------------- |
+| A handler recovers it, with `Respond.early` or `Effect.succeed` | resolves with the value → `<Await>`               |
+| `Respond.early(value)` raised directly                          | resolves with `value` → `<Await>`                 |
+| A handler throws it, with `Respond.throw` or `Effect.fail`      | rejects with an `ErrorResponse` → `useAsyncError` |
+| `Respond.throw(value, init)` raised directly                    | rejects with an `ErrorResponse` → `useAsyncError` |
+| A handler redirects, or a domain error has no handler           | rejects with a plain `Error`                      |
+| A defect or an interrupt                                        | rejects with a plain `Error`                      |
+
+The plain `Error` has the message `deferredFailureMessage` (`"Deferred route data failed"`) and no
+stack, in every server mode. The server logs the full cause of a defect. A recovered
+`Respond.early(value, init)` gives `value` without `init`, because a promise has no response.
+
+The deferred Effect can fail only with the factory's domain errors, `Respond.early` and
+`Respond.throw`. Any other error does not compile, and the message names the error tags. Handle
+those errors before `defer`, or make them defects with `Effect.orDie`. In a factory without domain
+errors, the deferred Effect must fail with `never`.
+
+The promise type includes what the handlers recover, so `Route.ComponentProps` types the value that
+`<Await>` renders. The type is `DeferredPromise<A>`, a subtype of `Promise<A>`. The
+`promiseInEffectSuccess` rule of the Effect language service reports only the global `Promise`
+type, so it does not report a `yield* defer(...)`.
+
 ## Provide services
 
 ### App-wide services with a runtime
@@ -255,19 +363,37 @@ makeEffectRouteFactory()(() => ({}));
 The runtime provides app-wide services. A request-scoped service is the current user, a request id,
 or a transaction for one request. There are two ways to provide one.
 
-The adapter option `requestContext` builds the services before React Router runs. Every middleware,
-loader and action sees them, and no middleware has to set them:
+A route-scoped router middleware on `ReactRouter.routes` provides services to React Router's
+requests. Every middleware, loader and action sees them, and no React Router middleware has to set
+them:
 
 ```ts
-ReactRouterHttp.make({
-  build: () => import("virtual:react-router/server-build"),
-  factory: routeFactory,
-  requestContext: (request) =>
-    Context.make(RequestInfo, {
-      id: request.headers.get("x-request-id") ?? crypto.randomUUID(),
-      startedAt: Date.now(),
+// server/app.ts
+const RequestServices = HttpRouter.middleware((app) =>
+  Effect.provideServiceEffect(
+    app,
+    RequestInfo,
+    HttpServerRequest.HttpServerRequest.use((request) =>
+      Effect.succeed({
+        id: request.headers["x-request-id"] ?? crypto.randomUUID(),
+        startedAt: Date.now(),
+      }),
+    ),
+  ),
+).layer;
+
+export const App = Layer.mergeAll(
+  ReactRouter.routes.pipe(Layer.provide(RequestServices)),
+  ReactRouterAssets.layer,
+).pipe(
+  Layer.provide(
+    ReactRouter.layer({
+      build: () => import("virtual:react-router/server-build"),
+      factory: routeFactory,
+      mode: import.meta.env.MODE,
     }),
-});
+  ),
+);
 ```
 
 A [middleware](https://reactrouter.com/how-to/middleware) can also provide services. An effect
@@ -308,14 +434,26 @@ A route Effect can then require the runtime's services and the request's service
 requirement is a compile error. `RequestContextKey<ReqServices>` is an alias of
 `RouterContext<Context.Context<ReqServices>>`.
 
+The adapter sets this key to the request fiber's context before React Router runs. That context
+holds the server span, `HttpServerRequest` and the services of the router middleware. Do not set the
+key to a new context in a React Router middleware, as an app without the adapter does. A new context
+replaces those services for every function after that middleware. Provide request services with a
+router middleware or an effect middleware, as this section shows.
+
 ## The adapter
 
-`react-router-effect/server` is a React Router adapter for Effect's Node HTTP server
-(`@effect/platform-node`). It handles everything between an `HttpServerRequest` and React Router. That
-is the Web `Request` and its abort signal, the route factory, and the client build. It also converts
-React Router's `Response`, with its streamed body and its cookies. The adapter is an
-Effect HTTP app like any other. The app serves it with its own Effect HTTP server and keeps its own
-middleware: logging, compression, tracing, proxies and other routes.
+`react-router-effect/server` is a React Router adapter for Effect's HTTP router, on every platform
+that the router runs on. It is the Effect counterpart of `@react-router/express`. It
+handles everything between an `HttpServerRequest` and React Router. That is the Web `Request` and
+its abort signal, the route factory, and the client build. It also converts React Router's
+`Response`, with its streamed body and its cookies. The app keeps its own server, middleware and
+routes.
+
+The adapter's API is unstable, and a minor version can change it. Every export of
+`react-router-effect/server` and `react-router-effect/vite` has the JSDoc tag `@stability unstable`.
+The route factory and the other exports of `react-router-effect` are stable, except the route
+metadata. The `routeMeta` configuration, the `Register` key `routeMeta`, `RouteMetaArgs`,
+`WithRouteMeta` and `routeMetaKey` are unstable, and a minor version can change them.
 
 React Router keeps doing what it does for any other server adapter: documents, `.data` requests,
 streamed promises, resource routes, the lazy route manifest and middleware. Before React Router
@@ -325,66 +463,165 @@ sees the build, the adapter runs every loader, action and middleware through you
   Its failures go through the factory's error handlers.
 - Any other route function passes through. Promise loaders and `makeLoader` wrappers keep working.
 
-The options:
-
-- `build` is the server build, or a function that loads it.
-- `factory` is the route factory.
-- `requestContext: (request) => Context` builds the request's services before React Router runs.
-- `clientAssets: true` serves the client build, `build.assetsBuildDirectory` under
-  `build.publicPath`, before React Router. Files under `assets/` use a content hash in their name,
-  and the adapter caches them for a year as immutable. It caches other files for an hour. It serves
-  the files as `express.static` does. A directory serves its index file, such as a prerendered page.
-  A directory path without the trailing slash redirects to the path with it. It does not serve
-  dotfiles, and a request it does not serve goes to React Router. Like `express.static`, it looks up
-  each GET and HEAD request in the file system. It serves only a build that it loads once: in
-  production mode, or a build value. It never serves a development build, where Vite serves the
-  client. `assetsBuildDirectory` is relative to the working directory of the server. If the adapter
-  cannot read it, making the app fails with a `ClientBuildError` that names the resolved directory.
-  It needs the platform's file system, which `NodeHttpServer.layer` provides.
-- `mode` is React Router's server mode. The default is `process.env.NODE_ENV`. In production the
-  adapter loads the build once.
-
-The Web request comes from `HttpServerRequest.toWeb`, body included. Effect's stream sends the
-`100 Continue` when React Router reads the body of a request that sends `Expect: 100-continue`.
-
-The request URL is the one Effect derives from the request. An app behind a proxy applies the
-headers it trusts in its own middleware, with `request.modify` or `HttpMiddleware.xForwardedHeaders`.
-The request signal aborts only if the response ends early. That happens when the client leaves while
-React Router runs, or while the body streams. A completed response never aborts it.
+The layers:
+
+- `ReactRouter.layer(options)` provides the `ReactRouter` service. Its options are these:
+  - `build` is the server build, or a function that loads it.
+  - `factory` is the route factory.
+  - `mode` is React Router's server mode, and you must give it. In a Vite app, pass
+    `import.meta.env.MODE`. React Router runs in production mode for any mode but `development`
+    and `test`, and so does the layer. At layer build, the layer loads a build value once, or a
+    build function in production mode. In `development` and `test`, a build function loads for
+    each request.
+  - `loadContext` makes React Router's load context for each request. Read
+    [The load context](#the-load-context).
+- `ReactRouter.routes` registers React Router as the catch-all route on `*`.
+- `ReactRouterAssets.layer` registers the files of the client build. Read
+  [The client build](#the-client-build).
+- `ReactRouterVite.layer`, from `react-router-effect/vite`, serves the app in development on Node.
+  Read [Development with Vite](examples/node/README.md#development-with-vite).
+
+Provide one value of `ReactRouter.layer` to every layer that reads the service, as `App` does with
+`Layer.provide`. Two values load the build twice.
+
+### The load context
+
+`loadContext` does for the adapter what `getLoadContext` does for `@react-router/express`. It
+returns an Effect of a `RouterContextProvider`. Plain loaders and actions, and `handleRequest` in
+`entry.server.tsx`, read its values with `context.get`. Route Effects read services from their
+Effect context. So give route Effects services with router middleware, not with `loadContext`.
 
-React Router logs and answers the errors of route code. If the adapter's own steps fail, for example
-a `requestContext` that throws, the adapter logs the error with `Effect.logError` and answers 500.
-The log goes to the loggers of the app's Effect runtime.
+```ts
+ReactRouter.layer({
+  build: () => import("virtual:react-router/server-build"),
+  factory: routeFactory,
+  mode: import.meta.env.MODE,
+  loadContext: (request) =>
+    Effect.sync(() => {
+      const context = new RouterContextProvider();
+      context.set(localeKey, request.headers["accept-language"] ?? "en");
+      return context;
+    }),
+});
+```
 
-### Development with Vite
+The Effect gets the services of the layer and the services of the request. The services of the
+request, such as its scope, win. The adapter adds its own keys to the provider. If the Effect dies,
+the client gets an empty 500.
 
-In development Vite serves the client. `react-router-effect/vite` runs Vite's middleware in front of
-the app, on Effect's Node HTTP server:
+### Routes and middleware
 
-```ts
-import { ReactRouterVite } from "react-router-effect/vite";
+The route that a request matches decides which middleware runs on it. Effect has three kinds of
+middleware:
 
-const vite = await createServer({ server: { middlewareMode: true } });
-HttpServer.serve(Effect.flatten(reactRouterApp).pipe(ReactRouterVite.devMiddleware(vite)));
+- A server middleware, the `middleware` option of `HttpRouter.serve`, wraps every request. It also
+  wraps the send of the response, so a change to the response with `Effect.map` does not reach the
+  client. `HttpMiddleware.compression` works there.
+- A global router middleware, `HttpRouter.middleware(fn, { global: true })`, wraps every route.
+- A route-scoped middleware, `HttpRouter.middleware(fn).layer`, applies only to the routes of the
+  layers that you provide it to.
+
+Route-scoped middleware selects the middleware of each kind of request. `HttpRouter.serve` logs
+every request. To leave file requests out of that log, provide `HttpRouter.disableLogger` to the
+assets layer only:
+
+```ts
+export const App = Layer.mergeAll(
+  ReactRouter.routes.pipe(Layer.provide(RequestServices)),
+  ReactRouterAssets.layer.pipe(Layer.provide(HttpRouter.disableLogger)),
+  HttpRouter.middleware(HttpMiddleware.compression(), { global: true }),
+).pipe(
+  Layer.provide(
+    ReactRouter.layer({
+      build: () => import("virtual:react-router/server-build"),
+      factory: routeFactory,
+      mode: import.meta.env.MODE,
+    }),
+  ),
+);
 ```
 
-In development, making the app does nothing but return it, so the server can make it for each
-request. Load the module that calls `ReactRouterHttp.make` through `vite.ssrLoadModule`. Then the route
-modules, the factory and the adapter share Vite's module graph. The example's `server.js` and
-`server/main.ts` do this.
+The order of two route-scoped middleware layers on one route is not fixed. If the order matters,
+join them into one middleware with `combine`:
+`HttpRouter.middleware(first).combine(HttpRouter.middleware(second)).layer`.
+
+These rules apply to the routes:
+
+- An exact route wins over a route with a parameter, and both win over a wildcard. So your own
+  routes and the files of the client build win over React Router's `*`.
+- A route of your own on `*` or `/*`, for a method that React Router's route has, collides with it.
+  Then the server fails to start. A route of your own with the path of a file of the client build
+  fails the same way.
+- If a HEAD request matches no HEAD route, it uses the GET route of its path. `ReactRouter.routes`
+  registers no HEAD route. So a GET route of your own answers HEAD, as it does in Express.
+- React Router's route takes the methods of `HttpMethod.all`: GET, POST, PUT, DELETE, PATCH,
+  OPTIONS, TRACE and QUERY, and HEAD through GET. A request with another method, such as PROPFIND,
+  gets a 404 from the router.
+- Register `ReactRouter.routes` at the root of the router. Under a prefix, React Router does not
+  get the path that it expects. To serve the app under a path, set React Router's `basename`.
+- The router ignores the case of the path. On a file system that is case-sensitive, a request for a
+  file with the wrong case matches the file's route and gets a 404.
+
+### The client build
+
+`ReactRouterAssets.layer` serves `build.assetsBuildDirectory` under `build.publicPath`, as the two
+`express.static` lines of React Router's Express template do. It needs the platform's file system,
+which `NodeHttpServer.layer` provides. A Cloudflare Worker serves the client build from its static
+assets, and does not use this layer.
+
+- The hashed directory is the directory of the build's manifest URL, such as `/assets`. React
+  Router's build writes files with a content hash in their names there. The layer caches them for a
+  year as immutable. A request under the hashed directory gets a 404 for a file that the directory
+  does not have. A path with `..` does not get out of the hashed directory.
+- Each other file gets its own route for GET and HEAD, and the layer caches it for an hour. At
+  server start, the layer reads the client build. If a file is added outside the hashed directory
+  later, the layer serves it only after a restart.
+- A directory with an `index.html`, such as a prerendered page, serves that file. Its path without
+  the trailing slash redirects to the path with it. A root `index.html`, such as a prerendered home
+  page, serves `/`, and React Router's catch-all yields to it.
+- If the manifest URL is not under `publicPath`, or it is at the root of `publicPath`, there is no
+  hashed directory. Then the layer caches every file for an hour.
+- The layer serves no dotfiles, such as `.vite/manifest.json`, as `express.static` does.
+- The layer registers nothing for a build that loads for each request, such as a development build.
+  Vite serves the client there. It also registers nothing for a `publicPath` on another origin.
+- `assetsBuildDirectory` is relative to the working directory of the server. If the layer cannot
+  read it, the server fails to start with a `ClientBuildError` that names the resolved directory.
+  If a file name has a `*`, the server fails to start with a `ClientBuildError` too, because the
+  router cannot match that name.
+
+### Requests
+
+The Web request comes from `HttpServerRequest.toWeb`, body included. On Effect's Node server, the
+request has the changes that middleware makes to the `HttpServerRequest`, such as the headers of
+`HttpMiddleware.xForwardedHeaders`. On a Web server, such as a Cloudflare Worker, React Router gets
+the runtime's own request. The README of each example describes the requests of its platform.
+
+If the client leaves while React Router runs or while the body streams, the response ends early, and
+the request signal aborts. A completed response never aborts it. On Cloudflare Workers, the abort
+comes from Cloudflare's own request signal. For the conditions of that abort, read the
+[Cloudflare example](examples/cloudflare/README.md#requests).
+
+React Router logs and answers the errors of route code. If the adapter's own steps fail, for example
+a `loadContext` that dies, the adapter logs the error with `Effect.logError`. Then it answers an
+empty 500. The log goes to the loggers of the app's Effect runtime.
 
 ### Cookies
 
 Set cookies from route code with React Router's cookie helpers, `createCookie` and the session
 storages, as in any React Router app. The adapter converts React Router's `Set-Cookie` values into
-the response's `cookies`, as `HttpServerResponse.fromWeb` does. Effect HTTP middleware around the
-adapter can read and change them like any other cookie. A response that replaces React Router's has
-none of them.
+the response's `cookies`, as `HttpServerResponse.fromWeb` does. A router middleware on
+`ReactRouter.routes` can read and change them like any other cookie. A response that replaces React
+Router's has none of them.
 
 Effect keeps one cookie per name and only the attributes it knows: `Max-Age`, `Domain`, `Path`,
-`Expires`, `HttpOnly`, `Secure`, `Partitioned`, `Priority` and `SameSite`. If one response sets the
-same cookie name twice, for example to expire it on one path and set it on another, only the last
-one is sent.
+`Expires`, `HttpOnly`, `Secure`, `Partitioned`, `Priority` and `SameSite`. One response can set the
+same cookie name twice, for example to expire it on one path and set it on another. Then Effect
+sends only the last one.
+
+Effect accepts only cookie names that are RFC 6265 tokens: letters, digits and
+``!#$%&'*+-.^_`|~``. React Router's `createCookie` and session storages also accept other names,
+such as `app/session` or `user:prefs`. The adapter does not send a cookie with such a name. It logs
+an error with the cookie's name instead. Give every cookie a token name.
 
 ### Content type
 
@@ -401,10 +638,15 @@ return new Response(Readable.toWeb(file) as ReadableStream, {
 
 ### Tracing
 
-When the request has a server span, the adapter traces React Router. The span comes from
-`HttpMiddleware.tracer` with a tracer that exports spans, such as `OtelTracer`. Each middleware,
-loader and action runs in a span of its own, such as `react-router.loader routes/todos`. The spans
-nest as React Router calls the functions. This is the example's `GET /todos`:
+When the request has a server span, the adapter traces React Router. If the app provides a tracer
+that exports spans, such as `OtelTracer`, Effect's HTTP server makes the server span. Give the
+tracer where the serve function reads it, as [Platforms](#platforms) tells. Effect serves each
+request with the services of that layer. A tracer that the serve function does not read makes no
+server span, so the adapter adds no spans. The README of each example shows where its tracer goes.
+
+Each middleware, loader and action runs in a span of its own, such as
+`react-router.loader routes/todos`.
+The spans nest as React Router calls the functions. This is the example's `GET /todos`:
 
 ```text
 GET                           the server span, with http.route=/todos
@@ -423,6 +665,12 @@ instrumentation traces nest there too, such as a database driver that a promise
 Without a server span, or with Effect's native tracer, whose spans go nowhere, the adapter adds no
 spans and no cost.
 
+The adapter sets `http.route` on the server span to the pattern of the matched routes, such as
+`/todos/:id`, once per request. It does this also for a page that runs no route function. A router
+middleware that opens a span of its own does not change that: the pattern still goes on the server
+span. A request that matches no route keeps the router's `*`. `ReactRouter.layer` reads the tracer
+once, at layer build. So it does not see a tracer that the app provides only inside a request.
+
 ## Route functions
 
 ### Plain Effect loaders, actions and middleware
@@ -455,10 +703,10 @@ export const middleware = [
   `Route.ComponentProps` types the data of an Effect loader or action, including what the factory
   recovers.
   - Hooks that take `typeof loader` or `typeof action`, such as `useFetcher<typeof action>()`,
-    read the data through React Router's `SerializeFrom`. It treats a function as a client
-    function when its argument has the members of client loader args, and gives client functions
-    their raw return value. Typegen's `Route.LoaderArgs` and `Route.ActionArgs` have those same
-    members, so for an Effect the hook would type the data as the Effect itself.
+    read the data through React Router's `SerializeFrom`. If the argument of a function has the
+    members of client loader args, `SerializeFrom` treats it as a client function. It gives a
+    client function its raw return value. Typegen's `Route.LoaderArgs` and `Route.ActionArgs` have
+    those same members, so for an Effect the hook types the data as the Effect itself.
   - Take the args through `EffectRouteArgs<Route.LoaderArgs>`. It makes `pattern` optional, so the
     argument no longer matches and the hook reads the brand. A loader without args needs nothing.
   - `RouteData<typeof loader>` reads the brand directly and applies React Router's serialization.
@@ -468,8 +716,8 @@ export const middleware = [
   and the span that it provides around `next()` reach every route Effect downstream. `context.set`
   keeps working. You cannot annotate a route array with an effect middleware as
   `Route.MiddlewareFunction[]`.
-- Action metadata: `actionMeta` in the factory config is read after every action resolves. The
-  adapter attaches it to the action's data under `__meta`.
+- Route metadata: `routeMeta` in the factory configuration is read after every loader and action
+  resolves. The adapter attaches it to their data under `__meta`.
 - Tests: `routeFactory.handlers.loader(loader)(args)` runs a route function as the server does.
 
 ### Register what the factory recovers
@@ -480,7 +728,7 @@ A plain Effect loader cannot see the factory's handlers. Declare what they recov
 declare module "react-router-effect" {
   interface Register {
     recover: { FormValidationError: { reply: SubmissionResponse } };
-    actionMeta: { realtimeEventIds: ReadonlyArray<string> };
+    routeMeta: { realtimeEventIds: ReadonlyArray<string> };
   }
 }
 ```
@@ -510,8 +758,10 @@ Type '{}' is missing the following properties from type ...:
 
 ### Requirements and limits
 
-- Effect 4.1 or later, React Router 8.3 or later for the adapter, and `skipLibCheck`. The brand
-  augments `Effect`, and TypeScript cannot test the variance annotations of that augmentation.
+- Effect 4.1 or later, and `skipLibCheck`. The brand augments `Effect`, and TypeScript cannot test
+  the variance annotations of that augmentation.
+- For the adapter, React Router 8.3 or later. The route factory, `makeLoader`, `makeAction` and
+  `makeMiddleware` also support React Router 7.16 or later.
 - A route module export must be a function. A bare `Effect` value is not a loader.
 - Prerendering (`prerender`) and RSC mode call the build without the adapter.
 
@@ -594,9 +844,10 @@ of a rejected promise. It flows through the same recover and throw handling as a
 
 ### Per-request services
 
-Without the adapter there is no `requestContext` option. Set the context key in a plain React Router
-middleware. The factory's `requestContext` reads it, and provides those services to the loader or
-action:
+Without the adapter, no router middleware runs before React Router. Set the context key in a plain
+React Router middleware. The factory's `requestContext` reads it, and provides those services to the loader or
+action. With the adapter, do not set the key this way, as
+[Per-request services](#per-request-services) tells. This is the pattern without the adapter:
 
 ```ts
 // app/request-context.server.ts
@@ -635,8 +886,8 @@ export const loader = makeLoader(() =>
 
 ## API
 
-- `makeEffectRouteFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond?, actionMeta? }))`
-  returns `{ makeLoader, makeAction, makeMiddleware, Respond, handlers }`. The config is a builder
+- `makeEffectRouteFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond?, routeMeta? }))`
+  returns `{ makeLoader, makeAction, makeMiddleware, Respond, defer, handlers }`. The config is a builder
   that receives the base `Respond`. All its fields are optional. The returned `Respond` is the base
   helpers merged with your `respond` extensions, and the base helpers win. `makeLoader` and
   `makeAction` are the same wrapper. `makeMiddleware` wraps a `Route.MiddlewareFunction`, and
@@ -644,6 +895,9 @@ export const loader = makeLoader(() =>
 - `handlers` (`loader`, `action`, `middleware`, `requestContext`) is the runner that the server
   adapter applies to every route module.
 - `Respond` has `early` (recover), `throw` and `redirect`, and the `respond` helpers that you add.
+- `defer` (unstable) starts an Effect and gives a `DeferredPromise` of its result for loader data.
+  Read [Defer data](#defer-data). The types `DeferredPromise`, `DeferDiagnose`, `DeferHandled` and
+  `DeferRecoverOf`, and the constant `deferredFailureMessage`, go with it.
 - `ReturnableDataError`, `ThrowableDataError` and `ThrowableRedirectError` are the library route
   errors. `isRouteError` narrows them.
 - `ErrorHandler<Err>` is the handler signature type.
@@ -651,10 +905,12 @@ export const loader = makeLoader(() =>
   effect context.
 - `EffectRouteArgs<Args>`, `EffectMiddlewareArgs<Middleware>`, `RouteData<F>` and `Register` are the
   types of plain Effect routes.
-- `react-router-effect/server` exports `ReactRouterHttp.make`, and the types `RouteEffectCheck` and
+- `react-router-effect/server` (unstable) exports `ReactRouter`, with `ReactRouter.layer`, `ReactRouter.routes`
+  and the `ReactRouter.Options` type, and `ReactRouterAssets`, with `ReactRouterAssets.layer` and
+  `ReactRouterAssets.ClientBuildError`. It also exports the types `RouteEffectCheck` and
   `RouteEffectFailures`.
-- `react-router-effect/vite` exports `ReactRouterVite.devMiddleware`, for development. It needs
-  `@effect/platform-node`.
+- `react-router-effect/vite` (unstable) exports `ReactRouterVite.layer` and the `ReactRouterVite.ViteDevServer`
+  type, for development on Node. It needs `@effect/platform-node`.
 
 ## Development