@rsc-kit/mcp 0.18.1 → 0.19.0

package/guides/feature-flags.md

@@ -0,0 +1,63 @@
+# Feature flags
+
+> Vercel's Flags SDK runs unchanged — flags/next, without Next.
+
+Nothing to install from here. The [Flags SDK](https://flags-sdk.dev) is
+framework-agnostic at its core, and its Next integration — `flags/next`,
+the one with `flag()`, `dedupe()` and the adapters — needs one thing from
+Next: `next/headers`, for `headers()` and `cookies()`. Those exist here
+under the same names and with the same shapes, one object per request,
+which is what the SDK's per-request dedupe keys on. The build answers
+`next/headers` with them, so the SDK runs as written:
+
+```sh
+bun add flags
+```
+
+```ts title="src/flags.ts"
+import { flag, dedupe } from 'flags/next'
+
+const visitor = dedupe(async ({ cookies, headers }) => ({
+  id: cookies.get('visitor')?.value ?? 'anonymous',
+  country: headers.get('x-vercel-ip-country') ?? headers.get('cf-ipcountry') ?? '',
+}))
+
+export const showBanner = flag<boolean, { id: string; country: string }>({
+  key: 'show-banner',
+  identify: visitor,
+  decide: ({ entities }) => entities?.country === 'GB',
+})
+```
+
+```tsx title="src/app/page.tsx"
+import { showBanner } from '../flags'
+
+export default async function Home() {
+  const banner = await showBanner()
+
+  return banner ? <Banner /> : null
+}
+```
+
+A flag reads the request, so the page that awaits one renders per visitor —
+the build says `headers() in run, cookies() in run stream per request` and
+stores the rest as a shell, given a `<Suspense>` or a `loading.tsx` above
+the read. That is the same line any `headers()` call earns; see
+[Static generation](/guides/static-generation). An adapter — Statsig,
+LaunchDarkly, Vercel's own — is the SDK's, configured the way its docs say.
+
+The discovery endpoint is a route handler in the shape a `route.ts` already
+has:
+
+```ts title="src/app/.well-known/vercel/flags/route.ts"
+import { createFlagsDiscoveryEndpoint, getProviderData } from 'flags/next'
+import * as flags from '../../../../flags'
+
+export const GET = createFlagsDiscoveryEndpoint(async () => getProviderData(flags))
+export const openapi = false
+```
+
+What does not carry over is `precompute()`: it is built on a Next
+middleware rewriting the url to a permutation, which is Next's routing.
+Read the flag in the page instead; a flag read under a boundary costs one
+streamed hole, not the page.

package/guides/fonts.md

@@ -110,6 +110,31 @@ export default function RootLayout({ children }) {
 the one file the first paint needs, usually the Latin regular; preloading all
 of them defeats the subsetting.
 
+## A font never blocks the page
+
+Text paints before the web font arrives, always. That is not a tuning
+choice; it is the rule everything below serves, and a font can break it in
+three ways, each of which the setup above has already closed:
+
+- **A stylesheet from another origin.** `<link href="https://fonts.googleapis.com/…">`
+  is render-blocking CSS from a host the browser has not connected to: a DNS
+  lookup, a TLS handshake and a round trip before the first paint, on every
+  cold load. Self-hosting through Fontsource keeps the `@font-face` rules in
+  your own stylesheet, which is inlined into the document.
+- **`font-display: block`, or none at all.** Without a `font-display`, the
+  browser is free to hide text for up to three seconds while it waits — the
+  invisible-text flash. Every rule the setup writes says `swap` (paint the
+  fallback now, swap when the font lands) or `optional` (paint once, in
+  whichever is ready). Never `block`, and never leave it unset in a rule you
+  own.
+- **Preloading everything.** A `<link rel="preload">` per file puts every
+  weight and subset ahead of the page in the network queue. Preload the one
+  file the first paint needs; the rest arrive with the stylesheet.
+
+A font that is slow — a cold cache, a throttled connection — then costs a
+swap or a fallback, never a blank page. The section below is how to make
+that swap invisible.
+
 ## Getting to 100 on a phone
 
 Fontsource's stylesheet is the right default and the wrong last mile. It

package/guides/forms.md

@@ -7,6 +7,21 @@ that handles the state for you, and a hook for when you want to hold it
 yourself. Both cover validation errors, pending state, optimistic updates and
 GET-form navigation.
 
+## The rule: uncontrolled, unless one field needs otherwise
+
+A form here is **uncontrolled by default**. Inputs keep their own value in
+the DOM, an initial value is React's `defaultValue`, and the action reads
+`FormData` on submit. No `useState` per field, no `value`/`onChange` pair,
+no re-render of the whole form on every keystroke — and after a refused
+submit the values are still there, because nothing re-rendered the inputs.
+
+Reach for a controlled field only where the UI has to react *as* the user
+types — a character count, a live preview, a dependent select — and bind
+that one field with `useField` (below), which scopes the re-render to it.
+Coming from react-hook-form this is the same default; coming from TanStack
+Form or from `useState`-per-input it is the opposite, and the difference is
+most of why these forms stay fast.
+
 ## The `<Form>` component
 
 The simplest way to handle forms. Works without any hooks — just pass a server action and use the render-prop for pending state and errors.
@@ -275,6 +290,54 @@ genuinely reloads. Then the server renders the page again, and putting the
 values back is the server's job — return them from the action and render them
 as `defaultValue`.
 
+### The schema is written for the shape it wants
+
+Every value in a `FormData` is a string or a file, and a control that is off
+is not there at all — a fact that used to leak into every schema as
+`z.coerce.number()` and a per-checkbox `.transform()`. It does not any more.
+The form is read *the way the schema means it*, on both sides:
+
+```ts
+const settings = z.object({
+  notify: z.boolean(),                 // unchecked posts nothing → false; "on" → true
+  limit: z.number().int().min(1),      // "5" → 5
+  tags: z.array(z.string()),           // one tag → ['a']; none ticked → []
+  policy: z.string().optional(),       // hidden behind a switch → absent when off
+  auth: z.discriminatedUnion('kind', [ // auth[kind] picks the branch
+    z.object({ kind: z.literal('none') }),
+    z.object({ kind: z.literal('bearer'), token: z.string().min(1) }),
+  ]),
+  rules: z.array(z.object({ on: z.boolean(), max: z.number() })),  // rules[0][on], rules[0][max]
+}).refine((s) => !s.notify || (s.policy ?? '').length > 0, {
+  path: ['policy'],
+  message: 'Say what to notify about.',
+})
+```
+
+Nothing in that schema knows it will meet a form. A schema describes itself
+(Standard JSON Schema — Zod 4 and ArkType do; Valibot not yet, and its
+values arrive as strings), and the decoder coerces to it: an absent
+`boolean` is `false`, `"on"`/`"1"` is `true`; a numeric string for a
+`number` is the number, an empty one for an optional number is absent; an
+`array` given one value is a list of one and given nothing is empty; nested
+names nest (`fields[0][name]` and `fields[0].name` alike); a union takes the
+branch its discriminator names; a control left blank is absent for a field
+the schema does not require, whatever its type — `z.email().optional()`
+accepts the empty input, an optional union is not read as its first branch
+— and is `""` for one it requires, so `z.string().min(1)` can say so. A value the schema refuses is still refused as itself — `"many"` for a
+number is the error you expect.
+
+A leaf JSON Schema cannot describe — `z.date()`, a custom check — costs only
+that leaf, which arrives as posted; the fields beside it are still read the
+way the schema means. A schema that cannot describe itself at all is said
+once, in development, with the library's reason.
+
+`<Form>` validates that object in the browser and the action decodes the
+same object on the server, from one codec, so a form that passes here passes
+there. A value sent through `<Form transform>` is encoded the same way back
+— a boolean as `"1"`/`"0"`, a nested object as `key[prop]` — and decodes to
+what was given.
+
 ### Lists of values
 
 A repeated name is an array:
@@ -405,6 +468,28 @@ and fades. It is state rather than a timer in every form that wants one,
 because the timer has to be cleared when the component goes away and that is
 the part people forget.
 
+### Nothing to save yet
+
+```tsx
+{({ dirty, reset }) => (
+  <>
+    <Button type="submit" disabled={!dirty}>Save</Button>
+    {dirty && <Button type="button" variant="ghost" onClick={reset}>Discard</Button>}
+  </>
+)}
+```
+
+`dirty` is whether anything differs from what the form started with. It is
+read from the form itself — a snapshot of its `FormData` on mount, compared
+on every input — so an uncontrolled field counts, which is the reason it is
+the form's to answer and not something a component beside it could work
+out. A successful submit makes the current values the new baseline;
+`reset()` goes back to the first one. A bound control with no native
+element behind it counts too, through the store. Only a form that reads
+`dirty` is measured, and it renders once when the value first differs — not
+on the keystrokes after — so a field that subscribes for itself keeps its
+promise of rendering alone.
+
 ### Why not a `<Field>` component
 
 TanStack Form and react-hook-form both hand you a field through a render prop —
@@ -519,6 +604,24 @@ the markup is submittable on its own. Someone who hits enter before the
 javascript arrives still reaches the server; the page reloads with the result
 instead of updating in place.
 
+What happens on the wire: React writes the action's id into the form as a
+hidden field and points the form at the page's own url, and the browser
+posts there. The host reads the fields, runs the action they name exactly as
+the enhanced path would have called it, and renders the page again with what
+it returned seated in the form that posted — so a refusal shows on its
+fields, `error('email')` and `fieldState` included, for a visitor with no
+javascript at all. A `redirect()` the action throws is followed as a
+document's would be; a cookie it sets is on the answer. Same origin only, as
+an action is, and the answer is never stored. A stored page is the one most
+likely to be submitted this way — it paints before its runtime arrives —
+which is why this is not optional.
+
+The seating is React's own `useActionState`, which `<Form>` uses under a
+wrapper bound to your action: React hands a form-state action a
+`(previousState, formData)` pair, and your action keeps taking the
+`FormData` alone. A `useActionState` of your own works the same way, with
+an action written for the pair.
+
 The two do not fight. The handler calls `preventDefault()` first, and React does
 not run a form action for a submit that was cancelled — so the enhanced path
 wins whenever there is one, and the native path is what is left when there is

package/guides/index.json

@@ -59,6 +59,11 @@
     "title": "Errors and 404s",
     "description": "What a visitor sees when a page throws, or asks for a url nothing answers."
   },
+  {
+    "slug": "feature-flags",
+    "title": "Feature flags",
+    "description": "Vercel's Flags SDK runs unchanged — flags/next, without Next."
+  },
   {
     "slug": "file-uploads",
     "title": "File uploads",
@@ -134,6 +139,11 @@
     "title": "Offline",
     "description": "Knowing when the server cannot be reached, and carrying on without it."
   },
+  {
+    "slug": "openapi",
+    "title": "OpenAPI",
+    "description": "A document derived from your route.ts files, and Scalar's page over it."
+  },
   {
     "slug": "ppr",
     "title": "Partial prerendering",

package/guides/installation.md

@@ -63,6 +63,7 @@ export default defineConfig({
       sourceDir: "src",
       outDir: "build",
       offline: true,
+      openapi: { info: { title: 'Example API', version: '1.0.0' } },
     }),
     react(),
   ],
@@ -259,12 +260,12 @@ for before they will run.
 There is nothing to install and nothing this package adds — Vite already owns
 this. Two rules and one declaration.
 
-Anything named `VITE_*` is **inlined into the client bundle** and ships to the
-browser, whether or not a browser file reads it. Everything else stays on the
-server, read through `process.env`.
+Anything named `PUBLIC_*` (or Vite's own `VITE_*`) is **inlined into the
+client bundle** and ships to the browser, whether or not a browser file reads
+it. Everything else stays on the server, read through `process.env`.
 
 The prefix is the whole boundary, so never put a secret behind it.
-`VITE_STRIPE_KEY` is a published key.
+`PUBLIC_STRIPE_KEY` is a published key.
 
 And one line never to write into a `.env`: `NODE_ENV`. Vite sets it itself —
 `development` under `vite`, `production` under `vite build` — and honours a
@@ -287,7 +288,7 @@ interface ViteTypeOptions {
 }
 
 interface ImportMetaEnv {
-  readonly VITE_API_URL: string;
+  readonly PUBLIC_API_URL: string;
 }
 ```
 
@@ -299,7 +300,7 @@ interface ImportMetaEnv {
 
 #### When they are read
 
-`import.meta.env.VITE_*` is a literal in the bundle: changing one means a
+`import.meta.env.PUBLIC_*` is a literal in the bundle: changing one means a
 rebuild. `process.env.*` is a live read, so the deploy's environment wins —
 with one exception the build makes for you. A route that reads an environment
 variable and nothing request-bound is frozen at build time, value included,
@@ -321,13 +322,18 @@ import { z } from 'zod';
 
 export const env = createEnv({
   server: { DATABASE_URL: z.string().url() },
-  clientPrefix: 'VITE_',
-  client: { VITE_API_URL: z.string().url() },
+  clientPrefix: 'PUBLIC_',
+  client: { PUBLIC_API_URL: z.string().url() },
   runtimeEnv: typeof process === 'undefined' ? import.meta.env : { ...import.meta.env, ...process.env },
   emptyStringAsUndefined: true,
 });
 ```
 
+`typeof process === 'undefined'` is not decoration: a `"use client"` file
+that imports this for a `PUBLIC_` value runs where there is no `process`,
+and `{ ...process.env }` there is a `ReferenceError` before the first
+render. The scaffold's `env.ts` is written this way.
+
 Read `env.DATABASE_URL` instead of `process.env.DATABASE_URL` and three things
 follow. It is a `string`, not `string | undefined`. A server variable touched
 from a client component throws by name rather than being silently `undefined`.

package/guides/laravel.md

@@ -127,6 +127,16 @@ already use. Vite **is** the renderer in development. It writes
 Laravel does not route is handed through to the address inside it. Stop the
 dev server and the file goes with it, and so does the proxy.
 
+Per url the rule is: **if the React tree has it, React renders it**;
+otherwise Laravel does. That holds for a url Laravel also routes — a fresh
+application ships `Route::get('/', …)` to its welcome page, and after
+install `/` is `resources/js/app/page.tsx`, not the welcome page. The build
+writes its route table to `bootstrap/rsc/vite/routes.json` on every `vite`
+and `vite build`, and the package registers those urls after `routes/web.php`
+loads, so a page added to the tree is routed on the next request. The
+welcome route can stay or go; it answers nothing while the page exists.
+Until the first `vite` there is no table, and Laravel answers everything.
+
 The other direction works too. The renderer reads `APP_URL` and
 `RSC_HOST_CALL_SECRET` from the app's own `.env`, and a url the route tree does
 not own — `/login`, a Blade page, a webhook, a file under `/storage` — is
@@ -232,7 +242,21 @@ method runs, which is where `ValidationException` usually comes from.
 
 A class under `app/Rsc/Actions/` is a server action. `rsc:action-manifest`
 writes the map, and the build writes a `"use server"` module beside your pages
-exporting one function per method, named `classMethod`:
+exporting one function per method, named `classMethod`.
+
+Make one with its guards already on it:
+
+```sh
+php artisan make:rsc-action Orders --method=cancel --auth --can=update,Order --revalidate=orders
+```
+
+`--method` per call (none makes the class invokable, reached as `orders`),
+`--auth` for `#[Authenticated]`, `--can=ability` or `--can=ability,Model` for
+`#[Can]`, `--middleware=throttle:60,1` for `#[Middleware]`, `--revalidate`
+for the `Rsc::revalidate()` line, and `--rpc` to make a class for `rpc()`
+under `app/Rsc` instead. A slash nests: `Billing/Invoices`. The attributes it
+writes are the ones the registry reads, so what you asked for at the prompt
+is what runs.
 
 ```php title="app/Rsc/Actions/Orders.php"
 namespace App\Rsc\Actions;
@@ -362,7 +386,8 @@ closer to a millisecond. What matters is how many *sequential* calls a page
 needs. A page with no `middleware.ts` middleware makes no guard call; sibling
 components awaiting `rpc()` are rendered concurrently, so their calls
 overlap — and calls issued in the same tick travel as **one** request, a
-batch the package answers in one Laravel request; `cache()` dedupes
+batch the package answers in one Laravel request, one line per call as
+each finishes, so a fast read is not held behind a slow one; `cache()` dedupes
 identical calls within a request; a frozen page makes none at all and a
 shell only for its holes. A guarded page is therefore typically two Laravel
 requests — the guard, then the batch of its reads — and a host-call-heavy app

package/guides/offline.md

@@ -65,8 +65,10 @@ rscKit({ offline: true })
 ```
 
 The build writes `sw.js` beside the assets and the generated entry registers
-it. With it on, a page you have visited survives a full reload with no network
-at all — not just a navigation, a reload — and comes back interactive.
+it — once the page has loaded, or at once if it already has by the time the
+runtime boots. With it on, a page you have visited survives a full reload
+with no network at all — not just a navigation, a reload — and comes back
+interactive.
 
 Everything else lives in one page's memory — the pages a boundary keeps
 mounted, the prefetch cache. Reload with no network and the browser shows its
@@ -86,7 +88,8 @@ on every navigation, so it happens on the first load.
 
 | | |
 | --- | --- |
-| hashed assets | at install, and answered from the cache forever after — the name changes when the bytes do |
+| what boots the app | at install: the scripts, stylesheets, fonts, manifest and icons, plus `/` and the offline page with the payloads they boot from. Not an image, a wasm module or the share card — those are cached the first time they are used, so an install costs what a first page costs and not a megabyte more |
+| any other hashed asset | the first time it is asked for, and from the cache forever after — the name changes when the bytes do |
 | a page you loaded | its document, and the payload it boots from |
 | a page you reached by link | its payload, and its document fetched once to go with it |
 | a page you never visited | nothing |
@@ -178,7 +181,9 @@ export default function Offline() {
 Nothing in the file makes it special. It is an ordinary route, and what makes it
 the fallback is that the build stored it and the worker precached it. It is also
 the one page that can honestly stand in for another, because it is about being
-offline rather than about the url it appears under.
+offline rather than about the url it appears under. It stands in for every
+navigation nothing can answer — a page the build stored but this browser
+never visited included.
 
 **It has to be static.** A fallback that renders per request cannot be served
 when there is no request to be made, so the build checks and says when it will

package/guides/openapi.md

@@ -0,0 +1,99 @@
+# OpenAPI
+
+> A document derived from your route.ts files, and Scalar's page over it.
+
+Every `route.ts` already says what an OpenAPI operation needs: the methods it
+exports, and the `params`, `searchParams` and `body` schemas beside them. So
+the document is derived, not written — the way Elysia derives its from the
+schemas on its routes — and it cannot go stale.
+
+```ts title="vite.config.ts"
+rscKit({
+  openapi: {
+    info: { title: 'Shop API', version: '1.0.0' },
+    servers: [{ url: 'https://api.shop.example' }],
+    security: [{ bearerAuth: [] }],
+    components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } } },
+  },
+})
+```
+
+`openapi: true` is the same with defaults. The document answers at
+`/openapi.json` (`path` moves it), as an api route the build stores, without
+middleware — a document exists to be read.
+
+## What a route contributes
+
+```ts title="src/app/api/orders/[id]/route.ts"
+import { z } from 'zod'
+import type { RouteContext } from '@rsc-kit/core/route-schema'
+
+export const params = z.object({ id: z.coerce.number().int() })
+export const searchParams = z.object({ expand: z.boolean().optional() })
+export const body = z.object({ title: z.string().min(1) })
+
+export const openapi = {
+  tags: ['Orders'],
+  PATCH: { summary: 'Rename an order' },
+  responses: { 200: { description: 'The order' } },
+}
+
+export async function GET(request: Request, { params }: RouteContext<typeof params>) { … }
+export async function PATCH(request: Request, { params, body }: RouteContext<typeof params, never, typeof body>) { … }
+```
+
+| from | into the document |
+| --- | --- |
+| the directory | the path: `/api/orders/[id]` → `/api/orders/{id}` |
+| each method export | an operation |
+| `params` | the path parameters' types; a segment with no schema is a string |
+| `searchParams` | one query parameter per property, required where the schema requires it |
+| `body` | the request body of `POST`, `PUT`, `PATCH`, `DELETE`, and a documented `422` |
+| a `middleware.ts` above | a `session` security requirement, and `401`/`403` |
+| `export const openapi` | anything else an operation may say — `summary`, `description`, `tags`, `responses` — shared, or per method under `GET`/`POST`/… |
+
+A schema contributes by describing itself as JSON Schema (Standard JSON
+Schema): Zod 4 and ArkType do; Valibot needs its own converter and
+contributes nothing yet. Response bodies are what a route declares in
+`openapi.responses` — a handler returns `Response`, so nothing else knows the
+shape — until a typed response helper carries it.
+
+`export const openapi = false` leaves a route out: the page that renders the
+document, a webhook meant for one caller. `{ DELETE: false }` leaves one
+method out. An app whose routes are mostly webhooks turns the default
+around with `rscKit({ openapi: { include: 'declared' } })`: only a route
+that exports `openapi` is documented, and a callback needs no line. `HEAD` and `OPTIONS` are never documented — the engine answers
+them for every route, and a file exporting `OPTIONS` for a CORS preflight is
+not describing an operation.
+
+## The page
+
+Scalar's API Reference is a route handler in this shape already, so the
+page is one file and none of it is ours:
+
+```sh
+bun add @scalar/nextjs-api-reference
+```
+
+```ts title="src/app/reference/route.ts"
+import { ApiReference } from '@scalar/nextjs-api-reference'
+
+export const GET = ApiReference({ url: '/openapi.json' })
+export const openapi = false
+```
+
+Stored at build like any route that reads nothing per request. Scalar's
+package is the app's dependency and the app's version; the engine ships no
+UI and no dependency for it, whether or not the document is on.
+
+## Coming from a hand-written spec
+
+A spec kept in a file has three parts, and two of them move:
+
+- the `paths` — delete them; they are the routes and their schemas now, and
+  the same `body` schema validates the request at runtime, which the
+  hand-written spec never did
+- `info`, `servers`, `security`, `components.securitySchemes` — into
+  `rscKit({ openapi })`
+- a route's `summary`, `tags` and response shapes — into its
+  `export const openapi`

package/guides/redirects.md

@@ -123,7 +123,18 @@ window, and nothing warns.
 ## From a server action
 
 An action is not a render, so there is no shell to be on either side of. Throw
-from the action and the client follows it:
+from the action — a plain `"use server"` function or one built from
+`createActionClient()` — and the client follows it as a navigation: the
+layouts stay mounted and the history entry the form was on is replaced, so
+Back does not return to the submitted form. A `<Form>` shows nothing for it;
+signing in and arriving is the success.
+
+To the caller, the action **resolves** — with `{ redirected: '/where' }` —
+once the navigation is under way. It does not throw: a `startTransition(async
+() => { await logOut() })` with no `catch` around it would otherwise reject
+into React, which unmounts the root, and a logout ended on a white page.
+There is nothing to catch; a component that awaited the action is on its
+way off the screen, and the object it got is safe to read any field of.
 
 ```ts title="src/actions.ts"
 'use server'

package/guides/server-actions.md

@@ -84,6 +84,12 @@ server with it.
 Files travel this way too, without any encoding of your own — see
 [File uploads](/guides/file-uploads).
 
+The id is a hash of the module and the export in a build —
+`9396f92f746f#createOrder` — and nothing about the file is in it. In
+development it is the module's path as Vite serves it
+(`/@fs/Users/…/actions.ts#createOrder`), which is what a
+`$ACTION_ID_…` hidden input in a form shows there; a build never carries it.
+
 ## Returning UI
 
 Step 5 is the same serialiser a page goes through, so an action can answer
@@ -269,11 +275,18 @@ forgotten `next()` would otherwise look exactly like a check that passed.
 ```ts
 const result = await createPost({ title: 'x', body: 'y' });
 
-result.data              // what the handler returned
-result.validationErrors  // { title: ['Too short'] }
-result.serverError       // 'Something went wrong.'
+result?.data              // what the handler returned
+result?.validationErrors  // { title: ['Too short'] }
+result?.serverError       // 'Something went wrong.'
 ```
 
+The `?.` is the type's, not decoration: an action that `redirect()`s
+resolves with `undefined` on the client — the page is on its way elsewhere —
+and `result.serverError` on that is a `TypeError` inside a transition, which
+unmounts the root. The type is `Promise<ActionResult<Data> | undefined>`,
+so the unasked read does not compile. In a test, where nothing redirects,
+`result!` is fine.
+
 Returned rather than thrown, and that is not a style choice: React serialises a
 rejected server action opaquely — production strips the message and leaves a
 digest — so a thrown validation error reaches the browser as "an error
@@ -357,6 +370,37 @@ one can be wired in without this package having an opinion about which. See
 [Writing to the response](/guides/authorization#writing-to-the-response) for
 where else it works, and where it does not.
 
+## Work the visitor should not wait for
+
+An audit row, a welcome email, a cache warm: the action's answer should not
+wait for it, and it must still finish. `after()` queues work to run once the
+answer is on its way:
+
+```ts
+'use server';
+
+import { after } from '@rsc-kit/core/request';
+
+export async function signup(formData: FormData) {
+  const user = await createUser(formData);
+
+  after(() => sendWelcomeEmail(user));
+  after(() => audit('signup', user.id));
+
+  redirect('/welcome');
+}
+```
+
+Why not a detached promise: on a long-lived process it happens to run to
+completion; on a Worker the isolate is torn down when the response ends
+unless the work was handed to the platform's `waitUntil`, so a promise nobody
+awaited dies silently — some of the time, which is the worst way. `after()`
+is the same call on every host: handed to `waitUntil` where one exists, kept
+by the process elsewhere. A rejection is reported to the log and never
+reaches the response, which has already gone. It works from a component, a
+`middleware.ts`, an api route and an action alike; outside a request — a
+build — the work simply runs.
+
 ## Two at once
 
 Nothing queues them. Each call is an ordinary `fetch`, so two submits fired
@@ -409,11 +453,11 @@ double-click sends two requests unless you disable the button.
 An action that fails does not answer with a Flight stream, so the client turns
 the response into an error before the decoder ever sees it:
 
-| Response | What the client throws | What you do |
+| Response | What the client does | What you do |
 | --- | --- | --- |
-| `X-RSC-Redirect` header | `ServerRedirectError` | Nothing — the browser is sent to the location. |
-| `422` | `ServerValidationError`, carrying `errors` | Show the messages. `<Form>` does it for you. |
-| Any other failure | `Error`, naming the status | Whatever the app needs. |
+| `X-RSC-Redirect` header | Starts the navigation and **resolves** with `{ redirected }` | Nothing — the page is on its way to the location, and there is nothing to catch. |
+| `422` | Throws `ServerValidationError`, carrying `errors` | Show the messages. `<Form>` does it for you. |
+| Any other failure | Throws `Error`, naming the status | Whatever the app needs. |
 
 ```tsx
 "use client";

package/guides/testing.md

@@ -54,6 +54,24 @@ there is the round trip. Here the function *is* the interesting part — the
 validation, the middleware, the authorisation — and it is a unit test.
 :::
 
+One line a port brings needs a stub: `import 'server-only'`. Keep it — the
+build honours it, and a client file that imports the module fails to build
+rather than shipping a secret. But under Vite the package resolves to an
+empty module on the server, and under `bun test` it is the real package,
+which throws on import; an action file that carries the line is not callable
+in a unit test until a preload stubs it. The scaffold ships the two files:
+
+```toml title="bunfig.toml"
+[test]
+preload = ["./tests/preload.ts"]
+```
+
+```ts title="tests/preload.ts"
+import { mock } from 'bun:test'
+
+mock.module('server-only', () => ({}))
+```
+
 ### Reading the request
 
 `cookies()`, `headers()` and the rest read from a scope the host opens per
@@ -120,7 +138,10 @@ that never ran, a stored page that should not have been, a `404` that came back
 otherwise — the first run pays for it, the rest do not, and an edit is picked
 up. It runs your own `build` script — `bun run build` under Bun, `npm run
 build` under Node — so what is tested is what ships, on the runtime it ships
-on. Pass
+on. Files the build wrote to `.output/public` — the hashed assets, `sw.js`,
+`manifest.webmanifest`, the icons — are answered too, the way Nitro's static
+layer answers them in production, so a test can prove a page's links resolve
+and not only that the page renders. Pass
 `{ build: false }` in a ci step that already built.
 
 One build and one loaded module per test run, shared across files. That is both