@rsc-kit/mcp 0.17.0 → 0.18.1

package/guides/response-headers.md

@@ -87,3 +87,25 @@ jar.set('name', 'value', {
 
 Names are validated as cookie tokens and `sameSite` / `expires` are checked, so
 a typo is an error rather than a header the browser quietly ignores.
+
+## What a response says about itself
+
+Two things, and they are not the same kind:
+
+**How it was served**, always: `X-RSC-Kit: stored`, `rendered` or `shell` on
+every response — a page from a file the build wrote, a page rendered for this
+visitor, or a stored shell with its holes rendered now. It is the header a
+developer reads in the Network tab when a page is slower than expected, the
+way `X-Nextjs-Cache` is, and a CDN rule or a health check can key on it. It
+names no product, so there is nothing to strip.
+
+**What built it**, by default: `X-Powered-By: rsc-kit` on every response and
+`<meta name="generator" content="rsc-kit">` in every document — what
+BuiltWith and Wappalyzer read. The name only, never the version: a version in
+every response is what a vulnerability scanner filters on. A policy that
+strips every framework identifier turns both off, which matters for the tag,
+since a proxy can strip a header but not a line inside the HTML:
+
+```ts title="vite.config.ts"
+rscKit({ identify: false })
+```

package/guides/seo-files.md

@@ -62,6 +62,51 @@ A relative url in any of them is made absolute with the root layout's
 `metadataBase`; without one, a relative url is a build error that says so.
 Any of the three may return a string instead, served as written.
 
+## A sitemap you do not write
+
+With no `sitemap.ts`, the build writes `/sitemap.xml` itself, from what it
+already knows: every page it stored and every url `generateStaticParams`
+listed, each with the build as `lastModified`. Left out: anything under a
+`middleware.ts` (a guard means not for everyone), a page the build could not
+render, and the not-found page. The build's table says so:
+
+```
+○  /sitemap.xml
+   written by the build: 5 urls; a sitemap.ts beside the root layout replaces it
+```
+
+It needs the root layout's `metadataBase` for the host; without one the line
+says it was not written. A `sitemap.ts` replaces it entirely — the moment you
+want a page the build cannot see (a post per database row without
+`generateStaticParams`) or a `changeFrequency`, write one.
+
+## How fresh
+
+Three choices, and the function decides — the same rule every route follows:
+
+| you write | served | fresh |
+| --- | --- | --- |
+| nothing | the build's own sitemap, stored | every deploy |
+| a `sitemap.ts` that reads the database | stored at build | every deploy |
+| a `sitemap.ts` that awaits `connection()` | rendered per request | every crawl |
+
+```ts title="src/app/sitemap.ts"
+import { connection } from '@rsc-kit/core/request';
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  await connection(); // per request — the same mark a page uses
+
+  const posts = await db.post.findMany({ select: { slug: true, updatedAt: true } });
+
+  return posts.map((post) => ({ url: `/blog/${post.slug}`, lastModified: post.updatedAt }));
+}
+```
+
+Without the `connection()` line the same function runs once at build and the
+answer is stored; the build's table shows `○` for a stored one and `ƒ` for
+one that runs per request. Reading the database at build is fine — it is the
+request that makes a route dynamic, not the data.
+
 ## How they are served
 
 Each file becomes an api route, and that decides the rest. A `sitemap.ts`

package/guides/testing.md

@@ -41,7 +41,7 @@ import { GET } from '../src/app/api/greet/[name]/route'
 
 test('greets by name', async () => {
   const res = await GET(new Request('https://app.test/api/greet/ada'), {
-    params: Promise.resolve({ name: 'ada' }),   // a promise, as the engine gives it
+    params: Promise.resolve({ name: 'ada' }),   // a promise, as the engine gives it - RouteContext types it so
   })
 
   expect(await res.json()).toEqual({ greeting: 'Hello, ada' })
@@ -118,7 +118,9 @@ that never ran, a stored page that should not have been, a `404` that came back
 
 `createTestApp()` builds when your source is newer than the last build, and not
 otherwise — the first run pays for it, the rest do not, and an edit is picked
-up. It runs your own `vite build`, so what is tested is what ships. Pass
+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
 `{ build: false }` in a ci step that already built.
 
 One build and one loaded module per test run, shared across files. That is both

package/guides/typed-routes.md

@@ -146,3 +146,20 @@ 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.
 :::
+
+## Regions
+
+`revalidate()` in an action and `refresh()` in the browser take a region by
+name, and the names are typed to the ones the build found: every
+`section('orders', …)` and every `@slot` directory, plus `'page'` and
+`'all'`. A typo, or a section renamed since, stops compiling instead of being
+refused by the renderer at runtime:
+
+```ts
+revalidate('orders')   // a section the build found
+revalidate('order')    // does not compile
+```
+
+A name computed at runtime is cast, as an href is: `revalidate(name as
+RevalidateTarget)`. A name that reaches the renderer unknown anyway is still
+refused with the names it does know.

package/guides/url-validation.md

@@ -86,12 +86,16 @@ 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'
+import type { RouteContext } from '@rsc-kit/core/route-schema'
 
 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 }) {
+export async function POST(
+  request: Request,
+  { params, body }: RouteContext<typeof params, typeof searchParams, typeof body>,
+) {
   const { id } = await params      // number
   const { title } = await body     // non-empty string
 
@@ -99,7 +103,9 @@ export async function POST(request: Request, { params, body }) {
 }
 ```
 
-Awaited, the same way a page awaits its props. That is not only symmetry: a
+`RouteContext` is `PageProps` for a route — each schema's output behind a
+promise, and with none, `RouteContext<'/api/posts/[id]'>` types `params` from
+the segments. 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

package/guides/where-it-runs.md

@@ -0,0 +1,168 @@
+# Where it runs
+
+> A host is a Nitro preset, not a server you write.
+
+There used to be a page here for each runtime, and a server file generated to
+match. There is no server file now, and no choice about it either:
+[Nitro](https://nitro.build) builds the server around the route tree, and
+choosing where an app runs is choosing a preset.
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite';
+import { nitro } from 'nitro/vite';
+import react from '@vitejs/plugin-react';
+import { rscKit } from '@rsc-kit/core/vite';
+
+export default defineConfig({
+  plugins: [
+    nitro({ preset: 'bun', serveStatic: 'inline' }),
+    rscKit(),
+    react(),
+  ],
+});
+```
+
+`bun create rsc-kit@latest my-app` writes that for you. Changing where it deploys is
+changing the one string.
+
+## The presets
+
+`rsc-kit` asks about three, because those are the ones it can check for you.
+Nitro carries [many more](https://nitro.build/deploy) and they need nothing from
+this package — a preset is a string, not an integration.
+
+| `--host` | preset | what you get |
+| --- | --- | --- |
+| `bun` | `bun` | `.output/server/index.mjs`, and `bun run compile` for a single binary |
+| `node` | `node` | `.output/server/index.mjs`, run with `node` |
+| `worker` | `cloudflare_module` | a Worker, plus the `wrangler.json` and `_headers` Nitro generates |
+
+Everything else — Vercel, Netlify, Azure, Deno, AWS Amplify — is the same
+change:
+
+```ts
+nitro({ preset: 'vercel', serveStatic: 'inline' })
+```
+
+## Running it
+
+```bash
+npm run dev      # vite is the renderer; nothing is prebuilt
+npm run build    # writes .output/
+npm run start    # runs .output/server/index.mjs
+```
+
+A Worker has no `start`, because it is deployed rather than started:
+
+```bash
+npm run preview  # wrangler dev, on workerd
+npm run deploy   # nitro deploy --prebuilt
+```
+
+## Compiling to a single binary
+
+Bun only, and the whole application ends up inside one file — engine, route
+tree and assets:
+
+```bash
+npm run compile   # builds, then bun build --compile
+./dist/app
+```
+
+It builds first on purpose. Compiling whatever `.output` happens to hold means
+a binary one version behind the source with nothing to say so — and on a
+project that has never been built, an `ENOENT` naming a path the app did not
+write.
+
+<Aside type="note" title="A Worker serves the frozen pages from a module">
+  A Worker has no filesystem, so the directory the build writes is not there
+  at request time. The build also writes the same pages as one module beside
+  the bundle, `rsc-static-inline.mjs`, which wrangler uploads with the rest
+  and the server imports when the directory is missing. Nothing to configure;
+  it is why `○` on a Worker means the stored page and not a live render that
+  happens to be the same. It counts toward the Worker's script size, which is
+  worth knowing on a site with hundreds of frozen pages.
+</Aside>
+
+<Aside type="note" title="Frozen pages stay outside the binary">
+  The build freezes pages into `.output/server/rsc-static` and the server reads
+  them from there. A compiled binary has no filesystem to read — the directory
+  is not embedded — so it renders those pages live instead. Everything still
+  answers; what you lose is the stored render, not the page.
+</Aside>
+
+<Aside type="caution" title="serveStatic: 'inline' is what makes this work">
+  Without it the binary compiles, starts, serves pages, and 404s every asset.
+  Inside a compiled binary the static path resolves into Bun's virtual
+  filesystem — where the files on disk are not — and the failure is
+  `ENOENT: /$bunfs/public/assets/…` with the pages themselves looking fine.
+
+  The generated config sets it. If you write your own, set it too.
+</Aside>
+
+## Native dependencies stay outside the bundle
+
+A package with a native binary — `sharp`, `bcrypt`, `better-sqlite3`,
+`@prisma/client` — cannot be rolled into a server bundle: the build succeeds
+and the server cannot load its own binary. The usual ones are left external
+by default, and Nitro traces each into `.output/server/node_modules` with its
+binaries, so the deployment is still one directory. For one that is not on
+the list:
+
+```ts
+rscKit({ serverExternalPackages: ['@acme/native-thing'] })
+```
+
+## Offline
+
+`rscKit({ offline: true })` writes a service worker into `.output/public`
+alongside the assets, so a page someone has visited survives a reload with no
+network. Off by default, and covered in [Offline](/guides/offline#surviving-without-one).
+
+## Why `nitro` is pinned
+
+The generated `package.json` pins an exact version rather than a range:
+
+```json
+"nitro": "3.0.260903-beta"
+```
+
+Nitro's own `latest` tag is a dated prerelease, and it sorts **above** the plain
+`3.0.0` on npm. So `^3.0.0` resolves to the older release, which builds without
+complaint and then answers 404 to every route. TanStack Start pins a dated beta
+for the same reason.
+
+## Assets are Nitro's
+
+The build writes browser assets to `.output/public`, and Nitro serves them from
+its own root. There is no `assetsDir` or `assetsUrl` to set: both were removed,
+and `rscKit()` refuses a config that still passes them rather than reading a
+prefix and ignoring it.
+
+The alternative was the silent version — the markup asks for the app's prefix,
+Nitro answers at its own, and the page arrives unstyled and never hydrates with
+nothing logged anywhere.
+
+Assets live in `.output/public` and are served by the same process that serves
+your pages. If you want nginx or a CDN serving them instead, point it at
+`.output/public` — that directory is the deployment.
+
+---
+
+Next: [Deploying →](/hosts/deployment)
+
+## Which entry point is whose
+
+`@rsc-kit/core/host` is the engine's front door for a **host adapter** — the
+handler, and beside it the few functions an adapter needs when it embeds the
+engine. Several of those are re-exports of app-facing modules, so an editor's
+auto-import may offer `redirect` or `revalidate` from `host`. They are the
+same functions; an app imports them from their own entry points:
+
+| in an app | not |
+| --- | --- |
+| `@rsc-kit/core/redirect` | `@rsc-kit/core/host` |
+| `@rsc-kit/core/revalidate` | `@rsc-kit/core/host` |
+
+Only an adapter imports `host`. The re-exports there are marked internal, so
+they sort below the app entry in a completion list.

package/guides/your-own-backend.md

@@ -0,0 +1,238 @@
+# Your own backend
+
+> The one endpoint a backend in any language answers.
+
+The model is a [BAP — Backend-Answered Pages](/hosts/backend-answered-pages);
+this page is the wire.
+
+There is no adapter to write on the JavaScript side. The renderer is what
+Nitro builds, on every host, and it already knows how to ask a backend for
+things: a server component calls `rpc()`, and the call leaves the process as
+an ordinary POST. What a backend implements is that one endpoint. Laravel's is
+[about 400 lines of PHP](/hosts/laravel); [Go's](/hosts/go) is about the same.
+
+This page is the contract, so a Rails, Django, .NET or Elixir application can
+answer it the same way.
+
+## Telling the renderer where you are
+
+Two variables, and the renderer wires itself. Both in development — `vite`
+reads the project's `.env` — and in production, where the built server reads
+its process environment:
+
+```ini title=".env"
+RSC_BACKEND=http://127.0.0.1:8080
+RSC_HOST_CALL_SECRET=a-long-random-string
+```
+
+`APP_URL` is read where `RSC_BACKEND` is absent, which is what makes a Laravel
+app need nothing extra. Optional beside them: `RSC_HOST_CALL_PATH` (default
+`/__rsc/host-call`) and `RSC_HOST_GLOBAL` (default `rpc`, the name server
+components call). Both, or neither: a secret without a backend has nowhere to
+go, and a backend without a secret is refused at the door — the renderer does
+not gate on one of the pair alone.
+
+Both are read when the first request arrives, not when the module loads, so
+they work wherever the built server runs: a process with an environment, or a
+Worker, where Nitro maps the bindings in `wrangler.json` — a `var` for the
+address, a `secret` for the secret — onto `process.env` per request. On a
+Worker the backend has to be reachable from Cloudflare's network, so it is an
+`https` origin behind the secret rather than a loopback address.
+
+Then the plugin's `hostCall` option overrides any of it for a setup that
+would rather not use the environment:
+
+```ts
+rscKit({ hostCall: { endpoint: 'http://127.0.0.1:8080', secret, path: '/__rsc/host-call' } })
+```
+
+## The request
+
+```http
+POST /__rsc/host-call
+Content-Type: application/json
+X-Rsc-Host-Secret: a-long-random-string
+Cookie: <the visitor's, forwarded unchanged>
+Authorization: <likewise, if the page request had one>
+
+{ "function": "Orders.recent", "args": [5] }
+```
+
+`function` is whatever the component passed to `rpc()`; the naming scheme is
+yours. `args` is positional, exactly as passed. `Cookie` and `Authorization`
+are the only headers copied from the page request — everything else either
+describes this POST or is meaningless to you — and they are what let the call
+run *as the visitor*: your session middleware reads the cookie and finds the
+same person the page is being rendered for. During a build there is no
+visitor and the headers are absent.
+
+**Check the secret first, in constant time, and refuse before dispatch.** This
+endpoint runs functions by name with none of your routing in front of it;
+`hash_equals('', '')` is true in PHP and its equivalents elsewhere, so an
+unconfigured secret has to be rejected before the comparison rather than
+trusted to it. Better still, do not register the endpoint at all when no
+secret is configured — absent, not open.
+
+## The reply
+
+JSON, and the fields keep the outcomes apart so the renderer never reads a
+message to tell an invalid form from a broken server:
+
+```json
+{ "result": [ … ], "revalidate": ["orders"] }
+```
+
+| you want to say | status | fields |
+| --- | --- | --- |
+| here is the answer | 200 | `result` |
+| …and the action made these regions stale | 200 | `result`, `revalidate: ["orders", "page"]` |
+| the input is invalid | 422 | `validationErrors: { "email": ["…"], "address.city": ["…"] }`, `error` |
+| there is no session | 401 | `unauthenticated: true`, `error` |
+| there is one, and still no | 403 | `unauthorized: true`, `error` |
+| go somewhere else | **200** | `redirect: "/login"`, optionally `redirectStatus` (default 307) |
+| a guard refused with its own status | that status | `error`, `refusalStatus: 429` |
+| the function failed | 500 | `error` |
+
+What each becomes on the other side: `validationErrors` reaches the form
+that submitted, each message under its input, dot-joined for a nested field
+and under `""` for a message about the form itself. `unauthenticated` and
+`unauthorized` become the engine's own `ServerAuthenticationError` and
+`ServerAuthorizationError`, so a page answers 401 or 403 the way it would
+have if a JavaScript guard had thrown them. `redirect` travels the path every
+other redirect travels — a real 3xx above a Suspense boundary, a digest below
+one. `revalidate` names [sections](/guides/sections) or `page`, and the answer
+to the action carries the re-rendered region with it rather than the browser
+being told to ask again.
+
+Two things that are easy to get wrong:
+
+**A redirect is a 200.** An HTTP client follows a 3xx transparently, so a real
+one here would send the host call itself to the destination and hand whatever
+it found back to the render as the function's result.
+
+**Refusing is not failing.** A form filled in wrongly is the ordinary case, and
+`validationErrors` is checked before `error` — a reply carrying both is read as
+a refusal with fields, not a failure with none. Reserve `error` alone, with a
+500, for the thing the visitor did not cause.
+
+## Batches
+
+Calls issued in the same tick of a render — sibling components each awaiting
+`rpc()` — arrive as one POST, so a page's parallel reads cost you one request
+rather than one each:
+
+```json
+{ "calls": [ { "function": "Orders.recent", "args": [5] }, { "function": "Me.profile", "args": [] } ] }
+```
+
+Answer with `replies`, one per call in order, each the reply it would have had
+alone plus the `status` it would have carried:
+
+```json
+{ "replies": [ { "status": 200, "result": [ … ] }, { "status": 401, "unauthenticated": true } ] }
+```
+
+Run every call, in order, and answer every one — a refusal in the second is
+that call's answer, not a reason to leave the third out. Each call's
+`revalidate` stays with that call. A backend that has not implemented this
+loses nothing but the saving: the renderer reads its "no function name" answer
+as "no batches here" and sends single calls from then on. Batches never mix
+visitors; every call in one carried the same forwarded headers.
+
+## Route middleware
+
+A `middleware.ts` beside or above a page may name guards in your vocabulary:
+
+```ts title="app/admin/middleware.ts"
+export const middleware = ['auth', 'can:manage-users']
+```
+
+Only the names, no default export: the engine's own guards are a
+`middleware.ts` *default export*, a function it runs itself, and a file may
+carry either or both. (`route.ts` may carry the names too, from before
+`middleware.ts` could.)
+
+The renderer does not know what those mean. Before anything at or below that
+directory renders — including a page frozen at build time, before the file is
+served — it calls the reserved function with the list:
+
+```json
+{ "function": "__rsc.middleware", "args": [["auth", "can:manage-users"]] }
+```
+
+Answer `{ "result": true }` to let the render go ahead. **Anything else is a
+refusal**: `false`, `null`, a string, an object, a 4xx, a connection error.
+The engine reads the literal `true` and nothing else, so a guard that aborts,
+redirects or simply throws keeps the page from rendering rather than being
+read as silence. Refuse with the fields above — `unauthenticated` when there
+is no session, `redirect` to send them to sign in, `refusalStatus` for a
+throttle's 429 — and the page answers accordingly.
+
+Run them in order, outermost first, and stop at the first refusal: an outer
+guard saying no means the inner one should never have been asked.
+
+## Server actions
+
+A `"use server"` function the browser can call is a name the renderer forwards
+to you. Write the map to `rsc-host-actions.json` at the project root before
+each build — the JavaScript name to whatever your side dispatches on:
+
+```json title="rsc-host-actions.json"
+{ "ordersCancel": "Orders.cancel", "profileUpdate": "Profile.update" }
+```
+
+The build writes `server-actions.generated.ts` in the source directory
+exporting each as an action, so a client component imports `ordersCancel`
+and calls it. Regenerate the file as part of `build` rather than by hand: a
+stale map names a method that has since been renamed, and nothing fails until
+the browser calls it. Laravel's `rsc:action-manifest` is this step; a Go
+registry writes the same file from the names it holds.
+
+## Urls you own
+
+The renderer forwards any url the route tree does not own — `/login`, a
+webhook, an uploaded file — to `RSC_BACKEND`, with `X-Forwarded-Host` and
+`X-Forwarded-Proto` set and the header `x-rsc-renderer-fallback: 1`. Trust
+the renderer as a proxy so your absolute urls come out against the public
+origin.
+
+If your application also proxies to the renderer — sitting in front of it,
+the way Laravel does with `RSC_RENDERER_URL` — two things keep a url neither
+side owns from bouncing between you forever:
+
+- Set `x-rsc-proxied-by-backend: 1` on what you forward. The renderer answers
+  404 itself instead of handing it back.
+- When a request arrives carrying `x-rsc-renderer-fallback`, answer 404 for
+  anything you do not route. It has already been through the renderer's table.
+
+Whichever process faces the internet, the host-call endpoint must not:
+restrict it at the web server, bind the listener to loopback, or serve it on
+a unix socket. The secret is the layer the protocol guarantees; the network
+is the one it cannot.
+
+## What the renderer expects of you
+
+- **Answer within 30 seconds.** A render blocked on a host that never answers
+  is a hung request, and the renderer gives up at 30s (`timeoutMs` on
+  `httpHostCalls`, for a host that embeds the engine itself).
+- **One process is not enough if you proxy.** A server that proxies a page
+  to the renderer holds a worker for the whole render, and the render calls
+  back to that same server for its data. With one worker, nobody is left to
+  answer. Laravel refuses `php artisan serve` for exactly this.
+- **A panic is one failed call.** Recover it into a 500 with `error`; the
+  other renders in flight should survive it.
+- **Serialise what you return as JSON.** It is decoded on the other side as
+  whatever `rpc<T>()` was told it is; there is no schema between you.
+
+## Testing it without the renderer
+
+The contract is plain HTTP, so a backend's own test suite can cover it
+without a JavaScript process: POST the request shape, assert the reply
+shape. Laravel's Pest suite does this; the Go adapter's `go test` does the
+same. The end-to-end proof — a real page rendered with data from your
+process — lives with the engine, which is where a rendering regression can be
+caught.
+
+---
+
+Reference implementations: [Laravel](/hosts/laravel) and [Go](/hosts/go).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsc-kit/mcp",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "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",
@@ -27,7 +27,7 @@
     "guides"
   ],
   "scripts": {
-    "test": "bun test tests",
+    "test": "tsc --noEmit && bun test tests",
     "typecheck": "tsc --noEmit",
     "build": "rm -rf dist guides && tsc -p tsconfig.build.json && node scripts/bundle-guides.mjs",
     "prepack": "bun run build"