@rsc-kit/mcp 0.14.0 → 0.15.0

package/guides/typed-routes.md

@@ -0,0 +1,139 @@
+# Typed routes
+
+> Links that fail the typecheck instead of the browser.
+
+Every build writes the urls it found to `.rsc-kit/rsc-routes.d.ts`.
+`Link`, `visit`, `prefetch` and `Form` accept only those.
+
+```tsx
+import Link from '@rsc-kit/core/Link'
+
+<Link href="/about">About</Link>       // ✅
+<Link href="/abuot">About</Link>       // ❌ typecheck fails
+```
+
+Dynamic segments work through ordinary template literals:
+
+```tsx
+<Link href={`/posts/${post.slug}`}>{post.title}</Link>   // ✅
+<Link href={`/postz/${post.slug}`}>{post.title}</Link>   // ❌
+```
+
+## There is no `route()` helper
+
+Deliberately. A template literal is already checked the same way a builder
+would check it, so a builder would only wrap what the language does for free.
+One existed and was removed.
+
+The one thing to watch is that a value you interpolate is url-safe.
+`` `/posts/${'a / b'}` `` type-checks and means three path segments — use
+`encodeURIComponent` when the value is not yours:
+
+```tsx
+<Link href={`/posts/${encodeURIComponent(slug)}`}>…</Link>
+```
+
+## Search params, typed by the page
+
+A page that [exports a `searchParams` schema](/guides/url-validation) has said
+what its query string means. The same schema types every link to it:
+
+```tsx title="src/app/search/page.tsx"
+export const searchParams = z.object({
+  q: z.string().default(''),
+  page: z.coerce.number().int().min(1).default(1),
+});
+```
+
+```tsx
+<Link href="/search" search={{ q: 'shoes', page: 2 }}>Page 2</Link>
+
+<Link href="/search" search={{ sort: 'asc' }}>…</Link>   // does not compile: the page never reads sort
+<Link href="/search" search={{ page: '2' }}>…</Link>     // does not compile: page is a number
+```
+
+A key the page requires is required on the link — a `q: z.string()` with no
+default makes `search` itself required, so the page's error boundary is not
+where a missing `q` is found. A page with no schema takes any scalars, and so
+does an href that is not one route (`path as Href`), because there is nothing
+to check it against.
+
+Values are typed by what the page will **see**, not what the schema accepts:
+`z.coerce.number()` takes anything in, and a link typed by that would take
+`page: 'two'`. Required-ness comes from the schema's input, the value from its
+output. Arrays repeat the key — `tags: ['a', 'b']` is `?tags=a&tags=b`, which
+is what `z.array()` parses back.
+
+For `visit()`, `prefetch()` and anything else that wants the string,
+`href()` runs the same check:
+
+```ts
+import { href } from '@rsc-kit/core/routes';
+
+visit(href('/search', { q: 'shoes', page: 2 }));
+```
+
+The build writes one line per route into `rsc-routes.d.ts` that reads the
+page module's `searchParams` export as a type. Nothing runs; a page without
+the export costs nothing.
+
+## Two limits
+
+**A dynamic segment widens.** `/posts/[slug]` becomes `` `/posts/${string}` ``,
+so `/posts/a/b` type-checks even though it does not match at runtime.
+
+**A list widens to `string`** unless you say what it is:
+
+```tsx
+const nav = [
+  { href: '/', label: 'Home' },
+  { href: '/about', label: 'About' },
+] satisfies { href: Href; label: string }[]
+```
+
+Without `satisfies`, TypeScript infers `string` for `href` and you lose the
+check.
+
+## If you never run the generator
+
+`.rsc-kit/rsc-routes.d.ts` is written by the build. Without it — or with a
+tsconfig whose `include` does not cover `.rsc-kit` — nothing is registered,
+every url-taking prop stays exactly as permissive as a plain `string`, and
+nothing breaks. There is no flag to turn this on.
+
+## `redirect()` is not typed
+
+Its destination is usually computed — read from a cookie, handed over by
+middleware — so typing it would make the common case a cast.
+
+## Api routes
+
+Every build writes the `route.ts` files it found as well, in their own union —
+so a `fetch` to an endpoint that no longer exists stops compiling:
+
+```ts
+import { apiUrl } from '@rsc-kit/core/routes'
+
+await fetch(apiUrl(`/api/orders/${id}`))
+await fetch(apiUrl('/api/ordrs'))          // does not compile
+```
+
+`apiUrl` returns what it was given. It exists because `fetch` takes any
+`string`, so without somewhere to put the type there is nothing to check
+against — the function is the place.
+
+**Pages and api routes are separate unions on purpose.** `<Link href="/api/health">`
+does not compile, because linking to an api route navigates the browser away to
+a json document; and `apiUrl('/orders')` does not compile either, because
+fetching a page gets html where json was expected. Each refuses the other's
+urls, which is the pair of mistakes worth catching.
+
+:::note[Paths, not response types]
+This checks the **url**. It does not infer what the endpoint returns — that
+would mean a typed `json()` helper of our own in place of `Response.json()`, and
+api routes are deliberately web standards with nothing of ours required in them.
+
+For end-to-end types without a fetch at all, a [server action or
+query](/guides/queries/) is already typed across the boundary: the return type
+is the function's, because it is the same function.
+:::

package/guides/url-validation.md

@@ -0,0 +1,143 @@
+# Typed URLs
+
+> Checking and typing params, query strings and request bodies with a schema you already write.
+
+A url is input from a stranger. `params` arrive as strings, `searchParams` as
+more strings, and `?page=banana` reaches your database as `NaN` unless
+something stopped it.
+
+Export a schema beside the page and it stops there instead:
+
+```tsx title="src/app/posts/[slug]/page.tsx"
+import { z } from 'zod'
+import type { PageProps } from '@rsc-kit/core/route-schema'
+
+export const params = z.object({ slug: z.string().min(1) })
+
+export const searchParams = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  tag: z.array(z.string()).default([]),
+})
+
+export default async function PostPage({ params, searchParams }: PageProps<
+  typeof params,
+  typeof searchParams
+>) {
+  const { slug } = await params        // string
+  const { page, tag } = await searchParams  // number, string[]
+}
+```
+
+Both are ordinary exports, read by the build the same way `metadata` and
+`generateStaticParams` are. Any [Standard Schema](https://standardschema.dev)
+works — Zod, Valibot, ArkType — because the schema is asked to validate itself
+and nothing here imports one.
+
+Three things you get that types alone cannot give you:
+
+- **`?page=3` arrives as `3`**, the number, not `"3"`.
+- **A missing value arrives as its default**, so there is no `undefined` branch
+  to write.
+- **A bad value is refused once**, at the edge, instead of surviving as `NaN`
+  into whatever the page does next.
+
+Export neither and nothing changes: `params` is the record of strings it always
+was, and `searchParams` is a `URLSearchParams`.
+
+## They fail differently, on purpose
+
+This is the part worth reading twice.
+
+| what was wrong | answer | why |
+| --- | --- | --- |
+| `params` | **404**, `not-found.tsx` | the url does not describe a page |
+| `searchParams` | nearest `error.tsx` | the page exists, the query was wrong |
+
+`/posts/` with a slug your schema refuses is not a broken page, it is an
+absent one — and a `500` tells a crawler to come back later while a `404` tells
+it the thing is gone. Meanwhile refusing a bad `?page=` as a 404 would let one
+bad link make a real page look deleted.
+
+The error carries the fields, so a boundary can say which one:
+
+```tsx title="src/app/posts/[slug]/error.tsx"
+'use client'
+
+import { isSearchParamsError } from '@rsc-kit/core/route-schema'
+
+export default function Error({ error }) {
+  if (isSearchParamsError(error)) {
+    return <p>That link is not quite right: {Object.keys(error.errors).join(', ')}</p>
+  }
+
+  return <p>Something went wrong.</p>
+}
+```
+
+## Repeated keys
+
+`?tag=red&tag=blue` arrives as an array and `?q=shoes` as a string, without the
+schema having to know which shape the url happened to take. So
+`z.array(z.string())` and `z.string()` both work on the key you would expect.
+
+## API routes take the same three
+
+Plus the body, which is the one that matters for a `POST`:
+
+```ts title="src/app/api/posts/[id]/route.ts"
+import { z } from 'zod'
+
+export const params = z.object({ id: z.coerce.number().int() })
+export const searchParams = z.object({ fields: z.string().optional() })
+export const body = z.object({ title: z.string().min(1), draft: z.boolean().default(false) })
+
+export async function POST(request: Request, { params, body }) {
+  const { id } = await params      // number
+  const { title } = await body     // non-empty string
+
+  return Response.json(await createPost(id, title), { status: 201 })
+}
+```
+
+Awaited, the same way a page awaits its props. That is not only symmetry: a
+route that never awaits `searchParams` provably does not vary by it, so the
+build can store one answer and serve it for `?utm_source=anything`. Resolved
+eagerly, that fact is unknowable and every tracking link misses the stored
+answer.
+
+The handler still takes a real `Request` and still returns a real `Response` —
+the schemas add a second argument and take nothing away. A route that exports
+none behaves exactly as it did before any of this existed.
+
+Statuses follow the same reasoning as a page, plus one:
+
+| what was wrong | answer |
+| --- | --- |
+| `params` | `404` |
+| `searchParams` | `400` with `{ message, errors }` |
+| `body` | `422` with `{ message, errors }` |
+
+`422` because that is what a [server action](/guides/validation/) already
+returns for a refused field, so a client has one shape to handle rather than
+two.
+
+JSON and form encodings both parse, since a url is posted to by `fetch` and by
+`<form>` alike. A body that is not valid JSON is a `422` about the body as a
+whole rather than a crash.
+
+:::caution[Exporting `body` reads the request]
+The schema consumes the stream, so `await request.json()` inside the handler
+will find it already read. Use the parsed value — that is the point of it.
+
+Only when you export a `body` schema, and only for `POST`, `PUT`, `PATCH` and
+`DELETE`. A `GET` handler is never touched.
+:::
+
+## What this is not
+
+A schema here checks the **shape** of a request, not whether the person making
+it may. `params.id` being a number says nothing about whose row it is — the
+caller chooses the id, and trusting it is the whole of an IDOR.
+
+Authorise on identity, in the handler, after the shape is known good. See
+[Authorization](/guides/authorization/).

package/guides/validation.md

@@ -0,0 +1,175 @@
+# Validation
+
+> Surfacing server-side validation errors in a form.
+
+Validation errors have one shape everywhere: a field name mapped to the
+messages for it.
+
+```ts
+{ title: ['The title must be at least 3 characters.'], body: ['The body is required.'] }
+```
+
+`ServerValidationError` carries that shape, and `<Form>`
+catch it and put it in `errors`. Nothing in a component has to know where the
+validation ran.
+
+## In a form
+
+```tsx title="src/components/PostForm.tsx"
+"use client";
+
+import { Form } from '@rsc-kit/core/Form';
+import { createPost } from '../actions';
+
+export function PostForm() {
+  return (
+    <Form action={createPost}>
+      {({ errors, pending }) => (
+        <>
+          <input name="title" />
+          {errors.title?.map((message) => <p key={message} className="error">{message}</p>)}
+
+          <textarea name="body" />
+          {errors.body?.map((message) => <p key={message} className="error">{message}</p>)}
+
+          <button disabled={pending}>Create</button>
+        </>
+      )}
+    </Form>
+  );
+}
+```
+
+No `try`/`catch`, and no state of your own. A successful submit clears
+`errors`; a failed one fills them.
+
+## Outside a form
+
+Catch it yourself, wherever the call rejects with one:
+
+```tsx
+"use client";
+
+import { ServerValidationError } from '@rsc-kit/core/errors';
+import { createPost } from '../actions';
+
+try {
+  await createPost(title, body);
+} catch (error) {
+  if (error instanceof ServerValidationError) {
+    setErrors(error.errors);
+  }
+}
+```
+
+## Producing one
+
+<Aside type="caution" title="The server half is the host's">
+  There is no validation library here, and no rule syntax to learn. What the
+  engine defines is the error the client understands — deciding that input is
+  invalid is your code's job, or your host's.
+</Aside>
+
+### Before it is submitted
+
+`<Form>` takes any [Standard Schema](https://standardschema.dev) —
+Zod, Valibot, ArkType, or anything else implementing it. There is no adapter
+per library and no import of one: the schema is asked to validate itself.
+
+```tsx title="src/components/PostForm.tsx"
+"use client";
+
+import { z } from 'zod';
+import { Form } from '@rsc-kit/core/Form';
+import { createPost } from '../actions';
+
+const schema = z.object({
+  title: z.string().min(3, 'Too short'),
+  body: z.string().min(10, 'Too short'),
+});
+
+export function PostForm() {
+  return (
+    <Form action={createPost} schema={schema}>
+      {({ errors, pending }) => (
+        <>
+          <input name="title" />
+          {errors.title?.map((m) => <p key={m} className="error">{m}</p>)}
+
+          <textarea name="body" />
+          {errors.body?.map((m) => <p key={m} className="error">{m}</p>)}
+
+          <button disabled={pending}>Create</button>
+        </>
+      )}
+    </Form>
+  );
+}
+```
+
+A failure fills the same `errors` you were already rendering and the action is
+never called — so a mistake costs no round trip, and an optimistic update never
+shows a row the server was going to refuse. Async schemas are awaited, so a
+uniqueness check works the same way.
+
+Field names follow the schema's paths: a nested field is `address.city`, and an
+issue belonging to no field — a cross-field rule like "these must match" — is
+under the empty string, so it has somewhere to be shown rather than being
+dropped.
+
+<Aside type="danger" title="A schema here is a courtesy, not a control">
+  It runs in the browser. The action is a public endpoint reachable without
+  this form — with `curl`, with the wrong values, in any order — so the server
+  still has to check. See [Authorization](/guides/authorization).
+
+  Use the same schema on both sides if you like; the point is that the one
+  running on the server is the one that decides.
+</Aside>
+
+### In a JavaScript action
+
+The same schema, on the side that decides. An action **returns** its failure
+rather than throwing one, so one line turns that into the error the form
+already understands:
+
+```ts title="src/actions.ts"
+'use server'
+
+import { schema } from './schema';
+
+export async function createPost(title: string, body: string) {
+  const parsed = await schema['~standard'].validate({ title, body });
+
+  if (parsed.issues) {
+    return { ok: false as const, issues: parsed.issues };
+  }
+
+  return { ok: true as const, post: await savePost(parsed.value) };
+}
+```
+
+```tsx title="src/components/PostForm.tsx"
+import { ServerValidationError } from '@rsc-kit/core/errors';
+import { issuesToErrors } from '@rsc-kit/core/standardSchema';
+
+async function submit(formData: FormData) {
+  const result = await createPost(
+    formData.get('title') as string,
+    formData.get('body') as string,
+  );
+
+  if (!result.ok) throw new ServerValidationError('Validation failed', issuesToErrors(result.issues));
+
+  return result.post;
+}
+```
+
+`issuesToErrors` is the same mapping the client-side check uses, so the field
+names match whichever side produced them.
+
+## ServerValidationError
+
+| Member | Type | What it holds |
+| --- | --- | --- |
+| `errors` | `Record<string, string[]>` | Field name to messages. |
+| `message` | `string` | A summary, for when there is nowhere to put field errors. |

package/guides/view-transitions.md

@@ -0,0 +1,120 @@
+# View transitions
+
+> What React's ViewTransition animates in an app built with this, and what it does not.
+
+React 19.3 ships [`<ViewTransition>`](https://react.dev/reference/react/ViewTransition),
+which animates a change by handing it to the browser's View Transition API.
+You can use it here. There is nothing to turn on, and no wrapper this package
+provides — it is React's component, used directly.
+
+It has one boundary worth knowing before you reach for it, because the failure
+is silence: a transition that does not run looks exactly like one you styled
+badly.
+
+| the change comes from | animates |
+| --- | --- |
+| your own `useState`, inside `startTransition` | yes |
+| a server action's result, put into state | yes |
+| `<Form>` — errors, success, optimistic updates | yes |
+| a streamed `<Suspense>` boundary arriving | yes, React does this on its own |
+| navigating to another page | yes, behind a flag |
+
+## What works
+
+Ordinary React. Give the changing element a `key` so React sees a replacement
+rather than an edit, and commit inside `startTransition`:
+
+```tsx
+'use client';
+
+import { useState, startTransition, ViewTransition } from 'react';
+import { addToTotal } from '../actions';
+
+export function Total() {
+  const [total, setTotal] = useState<number | null>(null);
+
+  return (
+    <>
+      <ViewTransition>
+        <p key={String(total)}>{total ?? '—'}</p>
+      </ViewTransition>
+
+      <button
+        onClick={() =>
+          startTransition(async () => {
+            const next = await addToTotal(1);
+
+            startTransition(() => setTotal(next));
+          })
+        }
+      >
+        add
+      </button>
+    </>
+  );
+}
+```
+
+A server action is in the working column for a reason worth stating: its result
+comes back as an ordinary return value, and what you do with it is `useState`.
+That makes it a transition like any other. `<Form>` is built on `useState`
+throughout, so everything it drives animates the same way.
+
+## Navigating between pages
+
+Off by default, because it changes how every navigation commits:
+
+```ts title="vite.config.ts"
+rscKit({ viewTransitions: true })
+```
+
+A build-time constant rather than a runtime setting, so an app that does not
+ask for it does not carry the boundary at all. What it animates is the segment
+a navigation replaces; what a page does inside itself needs no flag.
+
+## Coming back to a page you were just on
+
+A navigation to a page still being held reveals it rather than refetching it,
+so the form you were filling in is still filled in. That applies to a link, not
+only the back button — having one keep your work and the other throw it away is
+a distinction nobody makes while using an app.
+
+It is bounded, because the two halves pull against each other: what comes back
+is the tree from when you left, so its data is from then. Thirty seconds by
+default, which covers leaving a form to check something and coming straight
+back. Past that a link refetches.
+
+```ts
+import { setRevealWindow } from '@rsc-kit/core/navigate';
+
+setRevealWindow(0); // never reveal — every link is a fresh request
+```
+
+The back button is not bounded. It names a moment, and the page from that
+moment is the right answer however old it is.
+
+<Aside type="caution" title="It can hide a server that is down">
+  Revealing a held page fetches nothing, so those navigations keep working
+  when the backend does not. Measured with the process killed: a page visited
+  moments ago still navigates, one never visited does not. That is a reveal
+  window rather than offline support, and it means a dead server can go
+  unnoticed for as long as the window lasts — [`useOffline`](/guides/offline)
+  is what surfaces it. Actually surviving with no network is
+  [`offline: true`](/guides/offline#surviving-without-one), which is a service
+  worker and a different thing entirely.
+</Aside>
+
+## Requirements
+
+`react` and `react-dom` at **19.3 or newer**. A scaffolded app pins `^19.2`, so
+this is an upgrade:
+
+```bash
+npm install react@^19.3 react-dom@^19.3
+```
+
+React also documents a [`browser`](https://react.dev/reference/react-dom/browser)
+api for rendering a component only in the browser — the right tool for a value
+the server cannot know. It is not in 19.3 yet; see
+[static generation](/guides/static-generation#a-value-that-must-not-be-frozen)
+for what to do meanwhile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsc-kit/mcp",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "An MCP server over what an rsc-kit build decided: the routes, why each one is static or not, and what it costs the browser.",
   "type": "module",
   "license": "MIT",
@@ -23,12 +23,13 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "guides"
   ],
   "scripts": {
     "test": "bun test tests",
     "typecheck": "tsc --noEmit",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist guides && tsc -p tsconfig.build.json && node scripts/bundle-guides.mjs",
     "prepack": "bun run build"
   },
   "dependencies": {