@rsc-kit/mcp 0.20.13 → 0.21.1

package/guides/forms.md

@@ -53,6 +53,22 @@ export default function TodoForm() {
 
 The generic type parameter `<FormValues>` gives you autocomplete on `error()` and typed form data throughout the component.
 
+### Two words: `error` and `field`
+
+There is one way to read a form, and it is the same everywhere — in the render
+prop, in a component of its own, with shadcn or without:
+
+- **`error('title')`** — the field's message, or `undefined`. Show it, or test
+  it: `!!error('title')` is "invalid". Nested fields are paths:
+  `error('address.city')`, `error('items[0].name')`.
+- **`field('title')`** — a binding to spread onto a control, for the few fields
+  whose value this component has to hold. Most fields need nothing: they are
+  uncontrolled, the DOM holds the value, and it is read back on submit.
+
+Beside them: `pending`, `dirty`, `succeeded`, `recentlySucceeded`, `reset()` and
+`clearErrors()`. A field is checked when it is left and when the form is
+submitted, so `error()` never lights up on a field nobody has reached.
+
 ### Props
 
 ```text
@@ -68,17 +84,18 @@ replace — replace history state (GET forms)
 preserveScroll — keep scroll position (GET forms)
 ```
 
-### useFormStatus
+### In a component of its own
 
-Nested components can access form state via context, without prop drilling:
+`useForm()` returns exactly what the render prop gets, so a piece of a form
+moved into its own component is written the same way it was inline:
 
 ```tsx title="SubmitButton.tsx"
 "use client";
 
-import { useFormStatus } from "@rsc-kit/core/form";
+import { useForm } from "@rsc-kit/core/form";
 
 export function SubmitButton() {
-  const { pending } = useFormStatus();
+  const { pending } = useForm();
 
   return (
     <button type="submit" disabled={pending}>
@@ -88,14 +105,15 @@ export function SubmitButton() {
 }
 ```
 
+Not React's `useFormStatus`: that is a different hook with a different answer,
+which is why this one is not called that.
+
 ---
 
 ## Validation errors
 
-When a submit fails validation, `<Form>` fills `errors`
-themselves — there is no `try`/`catch` to write, and no state to hold. `errors`
-is `Partial<Record<keyof T, string[]>>`: each field maps to its messages, and
-`error('title')` returns the first one.
+When a submit fails validation, `error('title')` answers with the field's
+message — there is no `try`/`catch` to write, and no state to hold.
 
 Where those errors come from depends on the host, and the components do not
 care. See [Validation](/guides/validation).
@@ -198,11 +216,11 @@ any component that ends up rendering a real form control is already compatible:
 
 ```tsx
 <Form action={createPost} schema={schema}>
-  {({ pending, errors }) => (
+  {({ pending, error }) => (
     <>
       <Label htmlFor="title">Title</Label>
       <Input id="title" name="title" />
-      {errors.title?.[0] && <p className="text-destructive">{errors.title[0]}</p>}
+      {error('title') && <p className="text-destructive">{error('title')}</p>}
 
       <Select name="kind">
         <SelectTrigger><SelectValue /></SelectTrigger>
@@ -246,13 +264,13 @@ directly:
 
 ```tsx
 <Form action={reportBug} schema={formSchema}>
-  {({ pending, errors }) => (
+  {({ pending, error }) => (
     <FieldGroup>
-      <Field data-invalid={!!errors.title}>
+      <Field data-invalid={!!error('title')}>
         <FieldLabel htmlFor="title">Bug title</FieldLabel>
-        <Input id="title" name="title" aria-invalid={!!errors.title} />
+        <Input id="title" name="title" aria-invalid={!!error('title')} />
         <FieldDescription>Keep it short and specific.</FieldDescription>
-        <FieldError errors={errors.title?.map((message) => ({ message }))} />
+        <FieldError>{error('title')}</FieldError>
       </Field>
 
       <Button type="submit" disabled={pending}>
@@ -263,14 +281,14 @@ directly:
 </Form>
 ```
 
-`FieldError` takes `Array<{ message?: string }>`, and our `errors` are
-`string[]` per field — hence the one `map`. Everything else is the same markup
-you would write with any other form library.
+`FieldError` renders its children, and renders nothing when there are none —
+so `error('title')` goes straight in. Everything else is the same markup you
+would write with any other form library.
 
 The difference is where the errors came from. With TanStack Form or
-react-hook-form those are the *client's* validation; here they are the client's
-**and** whatever the server sent back, in the same object, because a refused
-action returns its fields rather than throwing them away.
+react-hook-form those are the *client's* validation; here `error()` answers with
+the client's **and** whatever the server sent back, because a refused action
+returns its fields rather than throwing them away.
 
 ### Setting the values
 
@@ -372,7 +390,7 @@ Names that describe a shape build it:
 
 Which is the shape your schema was written against — and the shape whose errors
 come back keyed the same way, because Standard Schema issue paths join with
-dots too. A refused `address.city` is `errors['address.city']`.
+dots too. A refused `address.city` is `error('address.city')`.
 
 Rows you add and remove are ordinary state; only the *names* have to line up:
 
@@ -393,8 +411,8 @@ react-hook-form's `<Controller>` render props:
 
 ```tsx
 <Form action={reportBug} schema={formSchema} defaultValues={{ description: '' }}>
-  {({ field, pending, errors }) => (
-    <Field data-invalid={!!errors.description}>
+  {({ field, error }) => (
+    <Field data-invalid={!!error('description')}>
       <FieldLabel htmlFor="description">Description</FieldLabel>
 
       <InputGroup>
@@ -404,7 +422,7 @@ react-hook-form's `<Controller>` render props:
         </InputGroupAddon>
       </InputGroup>
 
-      <FieldError errors={errors.description?.map((message) => ({ message }))} />
+      <FieldError>{error('description')}</FieldError>
     </Field>
   )}
 </Form>
@@ -421,35 +439,13 @@ source of truth, and nothing merges.
 Mix freely. Bind the one field that needs a character count and leave the rest
 alone.
 
-### How a field is doing
-
-`fieldState(name)` is the other half — what is *known* about a field, as
-opposed to what is spread onto it:
-
-```tsx
-{({ field, fieldState }) => {
-  const title = fieldState('title')
-
-  return (
-    <Field data-invalid={title.invalid}>
-      <FieldLabel htmlFor="title">Bug title</FieldLabel>
-      <Input id="title" {...field('title')} aria-invalid={title.invalid} />
-      <FieldError errors={title.errors.map((message) => ({ message }))} />
-    </Field>
-  )
-}}
-```
-
-Two objects rather than one, which is react-hook-form's split and it is right
-for a mechanical reason: `touched` and `invalid` are not DOM attributes, so a
-single spreadable object would put them on the element and React would warn
-about every one.
+### When a field is checked
 
 **A field is checked when it is left, not as it is typed.** An error that
 appears while someone is halfway through an email address is a form arguing
 with them; leaving the field is the moment they have finished saying what they
-meant. `touched` is what separates "not filled in yet" from "filled in
-wrongly".
+meant. So `error()` has nothing for a field nobody has reached yet, and there is
+no separate "touched" to consult before showing it.
 
 It works on ordinary uncontrolled fields too — the form listens for `focusout`
 rather than each field listening for `blur`, so `<Input name="title" />` is
@@ -517,42 +513,43 @@ one or two, for a character count or a control with no native element.
 When it is not, put the field in its own component and subscribe there:
 
 ```tsx
-import { useField } from '@rsc-kit/core/Form'
+import { useField } from '@rsc-kit/core/form'
 
 function Title() {
-  const { field, invalid, errors, ...bound } = useField('title')
+  const { field, error } = useField('title')
 
-  return <Input {...bound} aria-invalid={invalid} />
+  return <Input {...field} aria-invalid={!!error} />
 }
 ```
 
+The same two words, for one name: `field` to spread, `error` to show.
+
 `useField` re-renders **that component and nothing else** — not the form, not
 its siblings. Which is what `<Controller>` achieves with a render prop, except
 that the component you were going to write anyway is the boundary.
 
 So the scoping is there when a form is large enough to need it, and the flat
-markup is there when it is not. What their design also gives is per-field meta,
-and that needed no render prop either: it is `fieldState()`.
+markup is there when it is not.
 
 ### Reading the values from elsewhere
 
-`useFormValues()` reads them from anywhere inside the form — a preview, a
-summary, a count of what has changed:
+A preview, a summary, a count — something that shows a value without being the
+field — reads it the same way the field does:
 
 ```tsx
 function Preview() {
-  const { title } = useFormValues<{ title: string }>()
+  const { field } = useField('title')
 
-  return <h2>{title || 'Untitled'}</h2>
+  return <h2>{field.value || 'Untitled'}</h2>
 }
 ```
 
-Only **bound** values are here. An uncontrolled input's value belongs to the
-DOM, and nothing can know it changed without listening to it — bind a field with
-`field()` or `useField` and it appears.
+Only a **bound** value can be read this way. An uncontrolled input's value
+belongs to the DOM, and nothing can know it changed without listening to it —
+bind the field with `field()` or `useField` and it can be read.
 
 :::note[Inside the form, not outside it]
-Both hooks read a context, so they work anywhere below `<Form>`. That is usually
+`useForm()` and `useField()` read a context, so they work anywhere below `<Form>`. That is usually
 enough, because the `<form>` element can wrap as much of the page as you like,
 and a submit button outside it is `form="the-id"`.
 
@@ -582,9 +579,9 @@ function Page() {
 }
 
 function TopBar({ store }) {
-  const { title } = useFormValues<{ title: string }>(store)
+  const { field } = useField('title', store)
 
-  return <h1>{title || 'Untitled'}</h1>
+  return <h1>{field.value || 'Untitled'}</h1>
 }
 ```
 
@@ -593,8 +590,8 @@ optimistic updates. Creating it does not subscribe to it, so the component
 holding it does not re-render on every keystroke and take the whole subtree
 with it.
 
-`useField(name, store)` and `useFormValues(store)` take one explicitly;
-without one they read the context, which is what almost every form wants.
+`useField(name, store)` takes one explicitly; without one it reads the context,
+which is what almost every form wants.
 :::
 
 ## It works before hydration
@@ -609,7 +606,7 @@ 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
+fields, `error('email')` 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

package/guides/go.md

@@ -19,9 +19,10 @@ go get github.com/rsc-kit/go
 
 ## Wiring
 
-In a Go module, `init` sees `go.mod` and does the JavaScript half — the route
-tree, `vite.config.ts`, `.env` with `RSC_BACKEND` and a generated secret, the
-scripts — and prints the Go half for you to add:
+In a Go module, `init` sees `go.mod` and does the JavaScript half — the
+project's first `package.json` if it has none, the route tree,
+`vite.config.ts`, `.env` with `RSC_BACKEND` and a generated secret, the scripts
+— and prints the Go half for you to add. Nothing in the Go module is touched:
 
 ```sh
 bunx rsc-kit@latest init            # in the directory with go.mod

package/guides/installation.md

@@ -14,8 +14,10 @@ bun create rsc-kit@latest my-app
 ```
 
 It asks where it will run (Bun, Node or Cloudflare Workers), whether you want the
-React Compiler and which implementation, and whether to include Tailwind. Every
-answer has a flag, so it also runs unattended:
+React Compiler and which implementation, whether to include Tailwind, and
+whether the app should be installable — offline, a manifest and starter icons
+([`--pwa`](/guides/pwa#starting-one-installable)). Every answer has a flag, so it
+also runs unattended:
 
 ```sh
 bun create rsc-kit@latest my-app --host=bun --compiler=oxc --tailwind

package/guides/instrumentation.md

@@ -11,8 +11,8 @@ evaluates, and before the first request.
 // Runs at import, before any page: a bad variable stops the server here.
 import './env'
 
-// Anything asynchronous the app needs before it serves. The first render
-// waits for it.
+// Anything asynchronous the app needs before it serves. Called once per
+// process, at startup; the first render waits for it, later ones do not.
 export async function register() {
   await db.connect()
 }
@@ -35,10 +35,13 @@ the first page module evaluates. Importing a bootstrap module from every
 file that needs it works until someone forgets, and the failure is a page
 that throws "not configured" for the one visitor who reached it first.
 
-**Before the first request.** `register()` is awaited by every entry point
-a render can come through — the built server, the dev server, the
-prerender, a route's middleware check, a server action, an api route — so
-"before the first render" holds without the app knowing the list.
+**Before the first request.** `register()` is **called once**, and every
+entry point a render can come through — the built server, the dev server,
+the prerender, a route's middleware check, a server action, an api route —
+waits on that one call rather than making its own. After startup it has long
+since finished, so a request waits on nothing: it checks a promise that has
+already settled. That is how "before the first render" holds without the app
+knowing the list of entry points, and without a request ever paying for it.
 
 ## When it runs
 
@@ -49,9 +52,15 @@ prerender, a route's middleware check, a server action, an api route — so
 | `vite dev` | when the dev server first evaluates the app, and again when the file or anything it imports changes |
 | `vite build` | before the first page is prerendered |
 
-Once per process. A `register()` that resolved is not called again; one
-that rejected is retried by the next request, so a database that was not up
-yet is asked again rather than leaving the process permanently refusing.
+**Once per process, not once per request.** Measured on a built server and on
+a compiled binary, with a `register()` that logs: one call before the first
+request, and still one after a stream of them.
+
+A `register()` that resolved is not called again. One that *rejected* is the
+exception: the next request calls it again, so a database that was not up yet
+is asked again rather than leaving the process permanently refusing. On a
+server that case is rare in practice — a startup failure exits the process,
+below.
 
 On a server, a failure at startup — the file throwing at import, or
 `register()` rejecting — is reported and the process exits. A server that

package/guides/laravel.md

@@ -375,6 +375,14 @@ server {
 Laravel needs the renderer in `trustProxies` for `url()`, `route()` and its
 redirects to come out against the public origin rather than its own.
 
+Trusting it means trusting what it forwards, so the renderer drops any
+`X-Forwarded-For`, `Forwarded` or `X-Real-IP` the browser sent: otherwise a
+visitor would pick their own address for Laravel's throttles. The renderer
+cannot see the peer address to put in its place, so Laravel sees the
+renderer's. If the renderer sits behind a proxy of its own that writes those
+headers (a load balancer, Cloudflare), set `RSC_TRUST_FORWARDED=1` on the
+renderer and they are passed through.
+
 Setting `RSC_RENDERER_URL` puts Laravel in front instead: it proxies anything
 it does not route, which is what development does. In production it has the
 cost the caution above describes, at scale — a worker is held for the whole

package/guides/metadata.md

@@ -172,6 +172,18 @@ correctly, but the structured objects are the ones to write: they are typed,
 they take an image object with a width and height, and they are what a Next
 app already has.
 
+## On an iPhone's home screen
+
+`appleWebApp` is Next's shape — `capable`, `title`, `statusBarStyle`,
+`startupImage` — and renders the same tags. Launch screens are simpler as files
+named by their size; see [Splash screens](/guides/pwa#splash-screens).
+
+```tsx title="src/app/layout.tsx"
+export const metadata: Metadata = {
+  appleWebApp: { capable: true, title: 'Orders', statusBarStyle: 'black-translucent' },
+}
+```
+
 ## The share card
 
 ```tsx title="src/app/layout.tsx"

package/guides/navigation.md

@@ -75,13 +75,21 @@ because the two cost differently:
   same pictures are asked for again as urgent: a listing's tiles each
   preload their product's picture, and the one tapped first was queued
   behind the rest; asked for as high priority it moves to the front.
-- **The decode, on intent.** Decoding a payload loads the client chunks the
-  page names, and a landing page decoding its Sign in link for every visitor
-  loaded the sign-in page's thirty chunks onto phones that never tapped. So
-  the decode waits for the signal that says which link is meant: a pointer
-  that has settled on the link for 100 ms, a press, a touch. Each of those
-  leads its click by 60–300 ms — about a round trip — and the chunks load in
-  that time rather than after the click.
+- **The code for its client components, as the bytes land.** A payload names
+  each client component it renders, and the first eight a page renders are
+  loaded at idle the moment the payload arrives — the code only, nothing
+  rendered. Loaded at the touch instead, the first page of a visit waited on
+  its form's chunk *after* it had arrived, and showed its skeleton for a
+  quarter of a second; every later page found the chunk cached. Measured on an
+  iPhone, tapping through a fresh session: the first product page went from
+  ~325 ms with a skeleton to ~80 ms without one. Bounded per document, so a
+  landing page with a link to a heavy editor does not load the editor for
+  everyone.
+- **The decode, on intent.** Decoding the payload itself waits for the signal
+  that says which link is meant: a pointer that has settled on the link for
+  100 ms, a press, a touch. Each of those leads its click by 60–300 ms — about
+  a round trip — which is when the page is rendered hidden, so the click
+  reveals it.
 
 The click then reads a decoded tree, changes the url, and hands the page to
 React. Nothing on the network is between the click and the page unless the

package/guides/no-javascript.md

@@ -39,6 +39,13 @@ document itself. The build says so on the route's line. Fonts are the one
 thing left to you, because only you know which face the first paint needs —
 the [fonts guide](/guides/fonts) shows the two-line preload.
 
+Every other stored page gets the same, shells included. One that hydrates
+keeps its `<link>` as well, turned to `media="print"`: React looks for its
+stylesheets by href and would fetch a missing one again. The browser loads
+the print link at the lowest priority without holding up a paint, and never
+applies it on screen. A page rendered per request is not stored, and keeps
+its link.
+
 The default is not always the right call. A site of many small pages — a
 blog, documentation — may prefer one stylesheet the browser caches once over
 the same 4 kB repeated in every document, and a sheet just over the cap may

package/guides/ppr.md

@@ -53,8 +53,17 @@ a url it does know; the client sets the title again after hydration. Static
 
 ## A shell and the server that finishes it are one build
 
-A replay matches a slot by component **name**, so anything that renames a
-component between the build and the server breaks every slot below it.
+A replay matches a slot by component **name** — `displayName`, then `name` —
+so anything that renames a component between the build and the server breaks
+every slot below it. A bundler run over the build's output does exactly that
+when it merges module scopes: two different components of one name is
+ordinary (a wrapper named after the primitive it wraps), and the merge renames
+one of them.
+
+The build pins every component's name as it is in the build's output, as a
+`displayName` written into the server bundle. Whatever a later bundler calls
+the binding, React reads the name the shell recorded — which is why a page
+compiled into a single binary is resumed like any other, with no flag.
 
 
 A postponed state names the components React has to find when it replays, and
@@ -242,6 +251,10 @@ is the fix.
 `RSC_PPR_TIMEOUT_MS` sets it; the default is 2 seconds. Raising it lets slow
 pages be stored whole; lowering it pushes more of them to shells.
 
+The budget is per page, but pages do not wait in line for it. A page that has
+rendered what it can and is only waiting gives its place to the next, so a
+site of hundreds of shells costs about one budget, not one each.
+
 A page whose data resolves inside the budget is stored **whole**, even one that
 called `fetch()`. If a page must reflect the world at request time, what makes
 it so is reading the request — not a flag.