@rsc-kit/mcp 0.18.0 → 0.19.0

package/dist/index.js

@@ -20,6 +20,7 @@
 // Everything is read-only. There is no tool here that edits, builds or deploys,
 // deliberately: an agent already has a shell for those, and a server that can
 // change the project is one that can change it while answering a question.
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -61,7 +62,18 @@ const answering = (produce) => {
         throw error;
     }
 };
-const server = new McpServer({ name: 'rsc-kit', version: '0.1.0' });
+// The published version, read from this package's own manifest: the server
+// answered `0.1.0` to every client, which is the repo's placeholder and told
+// nobody which release they were talking to.
+const selfVersion = (() => {
+    try {
+        return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+const server = new McpServer({ name: 'rsc-kit', version: selfVersion });
 server.registerTool('list_routes', {
     title: 'List routes',
     description: 'Every route in this rsc-kit app, what the build did with each one, and how much javascript it ships. Start here when you need to know what exists.',

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n// An MCP server over what an rsc-kit build decided.\n//\n//   claude mcp add rsc-kit -- npx -y @rsc-kit/mcp\n//\n// Four questions, all answered from `build-report.json` and none of them\n// requiring the app to be running:\n//\n//   what routes exist, and what happened to each\n//   why is this one not stored\n//   which ones render per request\n//   which ones cost the browser the most\n//\n// Why a server rather than letting an agent read the file: the file is JSON\n// with a `type` field whose values mean nothing without the documentation, and\n// an agent reading it guesses — \"shell\" invites being treated as a failure when\n// it is the normal, correct outcome for a page with data in it. These answers\n// say what each state means, in the same words the build printed.\n//\n// Everything is read-only. There is no tool here that edits, builds or deploys,\n// deliberately: an agent already has a shell for those, and a server that can\n// change the project is one that can change it while answering a question.\n\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'\nimport { z } from 'zod'\nimport { explainRoute, heaviestRoutes, listRoutes, whatIsDynamic } from './answers.js'\nimport { NoReport, loadReport } from './report.js'\nimport { howTo, listTopics } from './recipes.js'\nimport { listGuides, readGuide, searchGuides } from './bundleGuides.js'\n\n/** The project to read, from the argument or the working directory. */\nconst root = process.argv[2] ?? process.cwd()\n\n/**\n * Loaded per call, never cached.\n *\n * A build happens while this server is running — that is the normal case, not\n * the exception — and an answer from the build before it is worse than a slow\n * one. The file is small and this is not a hot path.\n */\nconst read = () => loadReport(root)\n\n/**\n * Declared once, outside the call.\n *\n * Inline, TypeScript walks the sdk's tool generics against the zod shape and\n * gives up with \"type instantiation is excessively deep\" — a compiler limit\n * rather than anything wrong with the schema. A named const with the handler's\n * argument annotated stops the inference chain before it gets there.\n */\nconst URL_ARG = { url: z.string().describe('The url, e.g. /orders or /posts/hello') }\nconst TOPIC_ARG = { topic: z.string().describe('One of the topics from list_topics, e.g. forms or validation') }\nconst SLUG_ARG = { slug: z.string().describe('One of the slugs from list_guides, e.g. forms or server-actions') }\nconst PHRASE_ARG = { phrase: z.string().describe('A word or phrase, e.g. fieldErrors or metadataBase') }\n\nconst text = (body: string) => ({ content: [{ type: 'text' as const, text: body }] })\n\n/** A missing report is an answer, not a crash: it says to run a build. */\nconst answering = (produce: () => string) => {\n  try {\n    return text(produce())\n  } catch (error) {\n    if (error instanceof NoReport) return text(error.message)\n\n    throw error\n  }\n}\n\n/**\n * The registration surface, named rather than inferred.\n *\n * `registerTool` is generic over the zod shape, and TypeScript walks those\n * generics until it gives up — \"type instantiation is excessively deep\", which\n * is a compiler limit rather than anything wrong with the schema. Describing\n * the one method used, with the argument type written out, stops the inference\n * before it gets there and costs nothing: the schemas below are still real zod\n * and still validate at runtime.\n */\ninterface Registrar {\n  registerTool(\n    name: string,\n    config: {\n      title?: string\n      description?: string\n      inputSchema?: Record<string, unknown>\n      annotations?: { readOnlyHint?: boolean }\n    },\n    handler: (args: never) => Promise<{ content: { type: 'text'; text: string }[] }>,\n  ): unknown\n  connect(transport: StdioServerTransport): Promise<void>\n}\n\nconst server = new McpServer({ name: 'rsc-kit', version: '0.1.0' }) as unknown as Registrar\n\nserver.registerTool(\n  'list_routes',\n  {\n    title: 'List routes',\n    description:\n      'Every route in this rsc-kit app, what the build did with each one, and how much javascript it ships. Start here when you need to know what exists.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return listRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'explain_route',\n  {\n    title: 'Explain a route',\n    description:\n      'Why one url is stored at build time or rendered per request, what renders it, and what it costs the browser. Use this before changing a page to make it faster — the reason is recorded, not guessed.',\n    inputSchema: URL_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ url }: { url: string }) =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return explainRoute(report, url, builtAt, Date.now())\n    })) as never,\n)\n\nserver.registerTool(\n  'what_is_dynamic',\n  {\n    title: 'What renders per request',\n    description:\n      'The routes that render per request rather than being stored, each with the reason. This is the answer to \"why is this site not static\".',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return whatIsDynamic(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'heaviest_routes',\n  {\n    title: 'Heaviest routes',\n    description: 'The routes that make the browser download the most javascript, largest first.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return heaviestRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'how_to',\n  {\n    title: 'How to build it',\n    description:\n      'How to do something in an rsc-kit app — forms, prefetching, validation, the action client, data loading with TanStack Query or SWR, Suspense boundaries, offline, PWA, api routes, authorization, a Laravel or other backend, once-per-process startup, and why a page is dynamic. Read this BEFORE writing the code: the patterns here differ from Next and plain React in ways that compile either way. The short answer; read_guide has the full one.',\n    inputSchema: TOPIC_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ topic }: { topic: string }) => text(howTo(topic))) as never,\n)\n\nserver.registerTool(\n  'list_topics',\n  {\n    title: 'What this server can explain',\n    description: 'Every topic how_to knows about, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listTopics()),\n)\n\nserver.registerTool(\n  'list_guides',\n  {\n    title: 'The guides',\n    description: 'Every guide from docs.rsc-kit.dev, bundled with this server — the full text behind how_to, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listGuides()),\n)\n\nserver.registerTool(\n  'read_guide',\n  {\n    title: 'Read a guide',\n    description:\n      'The complete guide for one topic, as published at docs.rsc-kit.dev — routing, forms, server-actions, validation, metadata, testing, deployment and the rest. Use it when how_to is not enough or names something it does not explain.',\n    inputSchema: SLUG_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ slug }: { slug: string }) => text(readGuide(slug))) as never,\n)\n\nserver.registerTool(\n  'search_guides',\n  {\n    title: 'Search the guides',\n    description: 'Every line in the guides that mentions a word or phrase, with the guide it is in. Use it to find which guide covers something before reading it.',\n    inputSchema: PHRASE_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ phrase }: { phrase: string }) => text(searchGuides(phrase))) as never,\n)\n\nawait server.connect(new StdioServerTransport())\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n// An MCP server over what an rsc-kit build decided.\n//\n//   claude mcp add rsc-kit -- npx -y @rsc-kit/mcp\n//\n// Four questions, all answered from `build-report.json` and none of them\n// requiring the app to be running:\n//\n//   what routes exist, and what happened to each\n//   why is this one not stored\n//   which ones render per request\n//   which ones cost the browser the most\n//\n// Why a server rather than letting an agent read the file: the file is JSON\n// with a `type` field whose values mean nothing without the documentation, and\n// an agent reading it guesses — \"shell\" invites being treated as a failure when\n// it is the normal, correct outcome for a page with data in it. These answers\n// say what each state means, in the same words the build printed.\n//\n// Everything is read-only. There is no tool here that edits, builds or deploys,\n// deliberately: an agent already has a shell for those, and a server that can\n// change the project is one that can change it while answering a question.\n\nimport { readFileSync } from 'node:fs'\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'\nimport { z } from 'zod'\nimport { explainRoute, heaviestRoutes, listRoutes, whatIsDynamic } from './answers.js'\nimport { NoReport, loadReport } from './report.js'\nimport { howTo, listTopics } from './recipes.js'\nimport { listGuides, readGuide, searchGuides } from './bundleGuides.js'\n\n/** The project to read, from the argument or the working directory. */\nconst root = process.argv[2] ?? process.cwd()\n\n/**\n * Loaded per call, never cached.\n *\n * A build happens while this server is running — that is the normal case, not\n * the exception — and an answer from the build before it is worse than a slow\n * one. The file is small and this is not a hot path.\n */\nconst read = () => loadReport(root)\n\n/**\n * Declared once, outside the call.\n *\n * Inline, TypeScript walks the sdk's tool generics against the zod shape and\n * gives up with \"type instantiation is excessively deep\" — a compiler limit\n * rather than anything wrong with the schema. A named const with the handler's\n * argument annotated stops the inference chain before it gets there.\n */\nconst URL_ARG = { url: z.string().describe('The url, e.g. /orders or /posts/hello') }\nconst TOPIC_ARG = { topic: z.string().describe('One of the topics from list_topics, e.g. forms or validation') }\nconst SLUG_ARG = { slug: z.string().describe('One of the slugs from list_guides, e.g. forms or server-actions') }\nconst PHRASE_ARG = { phrase: z.string().describe('A word or phrase, e.g. fieldErrors or metadataBase') }\n\nconst text = (body: string) => ({ content: [{ type: 'text' as const, text: body }] })\n\n/** A missing report is an answer, not a crash: it says to run a build. */\nconst answering = (produce: () => string) => {\n  try {\n    return text(produce())\n  } catch (error) {\n    if (error instanceof NoReport) return text(error.message)\n\n    throw error\n  }\n}\n\n/**\n * The registration surface, named rather than inferred.\n *\n * `registerTool` is generic over the zod shape, and TypeScript walks those\n * generics until it gives up — \"type instantiation is excessively deep\", which\n * is a compiler limit rather than anything wrong with the schema. Describing\n * the one method used, with the argument type written out, stops the inference\n * before it gets there and costs nothing: the schemas below are still real zod\n * and still validate at runtime.\n */\ninterface Registrar {\n  registerTool(\n    name: string,\n    config: {\n      title?: string\n      description?: string\n      inputSchema?: Record<string, unknown>\n      annotations?: { readOnlyHint?: boolean }\n    },\n    handler: (args: never) => Promise<{ content: { type: 'text'; text: string }[] }>,\n  ): unknown\n  connect(transport: StdioServerTransport): Promise<void>\n}\n\n// The published version, read from this package's own manifest: the server\n// answered `0.1.0` to every client, which is the repo's placeholder and told\n// nobody which release they were talking to.\nconst selfVersion = (() => {\n  try {\n    return (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')) as { version?: string }).version ?? '0.0.0'\n  } catch {\n    return '0.0.0'\n  }\n})()\n\nconst server = new McpServer({ name: 'rsc-kit', version: selfVersion }) as unknown as Registrar\n\nserver.registerTool(\n  'list_routes',\n  {\n    title: 'List routes',\n    description:\n      'Every route in this rsc-kit app, what the build did with each one, and how much javascript it ships. Start here when you need to know what exists.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return listRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'explain_route',\n  {\n    title: 'Explain a route',\n    description:\n      'Why one url is stored at build time or rendered per request, what renders it, and what it costs the browser. Use this before changing a page to make it faster — the reason is recorded, not guessed.',\n    inputSchema: URL_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ url }: { url: string }) =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return explainRoute(report, url, builtAt, Date.now())\n    })) as never,\n)\n\nserver.registerTool(\n  'what_is_dynamic',\n  {\n    title: 'What renders per request',\n    description:\n      'The routes that render per request rather than being stored, each with the reason. This is the answer to \"why is this site not static\".',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return whatIsDynamic(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'heaviest_routes',\n  {\n    title: 'Heaviest routes',\n    description: 'The routes that make the browser download the most javascript, largest first.',\n    annotations: { readOnlyHint: true },\n  },\n  async () =>\n    answering(() => {\n      const { report, builtAt } = read()\n\n      return heaviestRoutes(report, builtAt, Date.now())\n    }),\n)\n\nserver.registerTool(\n  'how_to',\n  {\n    title: 'How to build it',\n    description:\n      'How to do something in an rsc-kit app — forms, prefetching, validation, the action client, data loading with TanStack Query or SWR, Suspense boundaries, offline, PWA, api routes, authorization, a Laravel or other backend, once-per-process startup, and why a page is dynamic. Read this BEFORE writing the code: the patterns here differ from Next and plain React in ways that compile either way. The short answer; read_guide has the full one.',\n    inputSchema: TOPIC_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ topic }: { topic: string }) => text(howTo(topic))) as never,\n)\n\nserver.registerTool(\n  'list_topics',\n  {\n    title: 'What this server can explain',\n    description: 'Every topic how_to knows about, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listTopics()),\n)\n\nserver.registerTool(\n  'list_guides',\n  {\n    title: 'The guides',\n    description: 'Every guide from docs.rsc-kit.dev, bundled with this server — the full text behind how_to, one line each.',\n    annotations: { readOnlyHint: true },\n  },\n  async () => text(listGuides()),\n)\n\nserver.registerTool(\n  'read_guide',\n  {\n    title: 'Read a guide',\n    description:\n      'The complete guide for one topic, as published at docs.rsc-kit.dev — routing, forms, server-actions, validation, metadata, testing, deployment and the rest. Use it when how_to is not enough or names something it does not explain.',\n    inputSchema: SLUG_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ slug }: { slug: string }) => text(readGuide(slug))) as never,\n)\n\nserver.registerTool(\n  'search_guides',\n  {\n    title: 'Search the guides',\n    description: 'Every line in the guides that mentions a word or phrase, with the guide it is in. Use it to find which guide covers something before reading it.',\n    inputSchema: PHRASE_ARG,\n    annotations: { readOnlyHint: true },\n  },\n  (async ({ phrase }: { phrase: string }) => text(searchGuides(phrase))) as never,\n)\n\nawait server.connect(new StdioServerTransport())\n"]}

package/dist/recipes.js

@@ -15,8 +15,15 @@
 const RECIPES = [
     {
         topic: 'forms',
-        summary: 'Submitting to a server action, with pending state and field errors',
-        body: `Use <Form>. It takes the server action itself, not a url.
+        summary: 'Submitting to a server action, with pending state and field errors. Uncontrolled by default - no useState per field',
+        body: `THE RULE: forms are UNCONTROLLED. Inputs keep their value in the DOM,
+an initial value is defaultValue, the action reads FormData. Do NOT write
+useState + value/onChange per input, and do NOT reach for TanStack Form.
+Control ONE field only when the UI must react as the user types (a character
+count, a live preview, a dependent select) - bind it with useField, which
+scopes the re-render to that field. Everything else stays uncontrolled.
+
+Use <Form>. It takes the server action itself, not a url.
 
 \`\`\`tsx
 'use client'
@@ -531,22 +538,30 @@ page that is 82 kB because of one <Link> is fine.`,
         body: `\`src/app/**/route.ts\`, one export per method:
 
 \`\`\`ts title="src/app/api/posts/[id]/route.ts"
+import type { RouteContext } from '@rsc-kit/core/route-schema'
+
 export const params = z.object({ id: z.coerce.number().int() })
 export const body = z.object({ title: z.string().min(1) })
 
-export async function GET(request: Request, { params }) {
+export async function GET(request: Request, { params }: RouteContext<typeof params>) {
   const { id } = await params
 
   return Response.json(await findPost(id))
 }
 
-export async function POST(request: Request, { params, body }) {
+export async function POST(request: Request, { params, body }: RouteContext<typeof params, never, typeof body>) {
   const { title } = await body
 
   return Response.json(await createPost(title), { status: 201 })
 }
 \`\`\`
 
+TYPE THE CONTEXT: RouteContext<'/api/items/[id]'> types params from the
+route's segments (the pattern is checked against the routes the build found);
+RouteContext<typeof params> from a schema. Every field is a PROMISE - a sync
+params.id is a compile error, never a route that 404s. Do NOT hand-write
+{ params: { id: string } }.
+
 A real \`Request\` in, a real \`Response\` out. \`params\`, \`searchParams\` and
 \`body\` are awaited, the same way a page's props are.
 
@@ -556,17 +571,31 @@ build found:
     import { apiUrl } from '@rsc-kit/core/routes'
     await fetch(apiUrl('/api/posts/' + id))
 
-Pages and api routes are separate unions: Link refuses an api url, apiUrl
-refuses a page. It checks the PATH, not the response type - for types across
-the boundary use a server action or a query, where the return type is the
-function's because it is the same function.
+A route.ts is a Route too (type Route from '@rsc-kit/core/routes' covers pages
+AND route.ts files, as Next's does): Link, visit and redirect accept it. The
+client treats a link to a route as an anchor - never prefetched, a full
+navigation, not a payload fetch. ApiRoute is the narrower union for apiUrl:
+apiUrl refuses a page, because fetching one gets html. It checks the PATH, not
+the response type - for types across the boundary use a server action or a
+query, where the return type is the function's because it is the same function.
 
 They run their directory's \`middleware.ts\`, so an endpoint under a guarded
 path is guarded.
 
 A \`GET\` that reads nothing from the request is answered from disk. Awaiting
 \`searchParams\` says the answer depends on the query; never touching it means
-the stored answer is served for any query at all.
+the stored answer is served for any query at all. NEVER read the query with
+new URL(request.url).searchParams (the Next way): the build cannot see that
+read, and reading request.url at all makes the route dynamic (the table says
+"reads the request - url"). A webhook verification handshake (hub.mode,
+hub.challenge) reads the awaited searchParams. A GET that answers 4xx/5xx to
+the build is never stored either (the table says "answered 403 to the build").
+
+redirect() thrown from a handler is the route's answer: a real 3xx Location
+for whoever asked (a signed-url export, a moved endpoint); notFound() is its
+404. A guard's redirect above a route.ts is a refusal: a browser that
+navigated there gets the Location, code that fetched it gets 401 +
+X-RSC-Redirect (fetch would follow a Location and hand back the login page).
 
 Exporting a \`body\` schema consumes the stream, so \`request.json()\` inside the
 handler will find it already read. Use the parsed value.
@@ -614,7 +643,7 @@ opts out, and the accessors are async:
 \`\`\`ts
 import { cookies, headers, searchParams, connection } from '@rsc-kit/core/request'
 
-const theme = (await cookies()).get('theme')
+const theme = (await cookies()).get('theme')?.value   // { name, value } | undefined, as in Next
 await connection()   // "render this per visitor", said deliberately
 \`\`\`
 
@@ -750,6 +779,61 @@ scores 99. Three moves:
    range you ask for (font-weight: 400 500) so nothing requests a missing file.
 Put the preloads before the <style> with the faces. Measured on rsc-kit.dev:
 Speed Index 1.7s to 0.9s, 99 to a steady 100, fonts 114 kB to 74 kB.
+THE RULE: a font never blocks the page - text paints in the fallback before
+the web font arrives. Three ways to break it, all avoided: a fonts.googleapis
+<link> (render-blocking CSS from a cold origin - self-host via Fontsource
+instead), font-display: block or unset (invisible text for up to 3s - every
+rule says swap or optional), preloading every file (preload only what the
+first paint needs).
+
+AFTER THE ANSWER: after(() => sendEmail(user)) from @rsc-kit/core/request
+queues work to run once the response is on its way - from an action, a
+component, middleware or an api route. Do NOT use a detached promise: on a
+Worker the isolate dies with the response unless work is handed to
+waitUntil, which after() does; on a process it runs detached. Rejections
+are logged, never surfaced.
+
+WRITE THE SCHEMA FOR THE SHAPE IT WANTS. The form is read the way the schema
+means it, on both sides (Zod 4 / ArkType describe themselves as JSON Schema;
+Valibot not yet - its values arrive as strings):
+  notify: z.boolean()             // unchecked posts nothing -> false; "on" -> true
+  limit:  z.number().int()        // "5" -> 5. NOT z.coerce.number()
+  tags:   z.array(z.string())     // one -> ['a'], none ticked -> []
+  policy: z.string().optional()   // hidden behind a switch -> absent when off
+  + .refine((s) => !s.notify || s.policy) for "required when the switch is on"
+Nested names nest: fields[0][name] / fields[0].name -> { fields: [{ name }] };
+auth[kind] picks a discriminated union's branch. No per-checkbox transform,
+no checkbox() helper. The action decodes the same object the form validated.
+Offline (rscKit({ offline: true })): the precache is what boots the app - js,
+css, fonts, manifest, icons, / and /offline with their boot payloads; images,
+wasm and the share card are cached on first use. A frozen page never visited
+falls back to /offline like any other navigation. Do not add a second service
+worker or a precache list; app/sw.js is importScripts'd into this one.
+
+An action that redirect()s RESOLVES with { redirected: '/where' } on the
+client once the navigation starts - it does not throw, so a plain
+startTransition(async () => await logOut()) needs no catch (a rejection
+there unmounts the root). The result is always an object (exactly one of
+data / validationErrors / serverError / redirected is set), so reading any
+field of it is safe. Do NOT wrap actions in a hook to catch
+ServerRedirectError; nothing throws.
+
+Before hydration a submit is a native POST to the page's url (React's hidden
+$ACTION_ fields); the host runs the action and re-renders the page with the
+result seated in the <Form> that posted - a refusal shows on its fields
+without javascript; a redirect() is followed, a cookie lands. Nothing to
+configure; <Form> uses useActionState under a wrapper so the action keeps
+its (formData) signature.
+A blank control is absent for any optional field (z.email().optional()
+accepts it; an optional union is not read as its first branch) and "" for a
+required one (z.string().min(1) refuses it). A leaf
+with no JSON Schema (z.date()) arrives as posted; its siblings still coerce.
+<Form ref={...}> is fine: the caller's ref is filled beside the form's own.
+Render props also carry dirty (anything differs from mount, uncontrolled
+fields included; baseline moves on a successful submit; reset() clears it):
+{({ dirty, reset }) => <Button disabled={!dirty}>Save</Button>} - the RHF
+isDirty gate for Save/Discard.
+
 Full guide: read_guide({ slug: 'fonts' }).`,
     },
     {
@@ -772,15 +856,23 @@ IMPORTS
   Metadata                     -> @rsc-kit/core/metadata (metadataBase, openGraph, twitter, icons as-is)
   app/robots.ts, app/sitemap.ts -> the same files and shapes; app/llms.ts beside them (how_to seo-files)
   middleware.ts subdomain rewrite -> nothing: a host is a route segment (how_to domains)
+  flags/next (Vercel Flags SDK) -> unchanged: the build aliases next/headers to @rsc-kit/core/request
+                                  (how_to feature-flags); precompute() does not carry over
   next/font                    -> Fontsource (how_to fonts)
   next/image                   -> unpic or vite-imagetools (how_to images)
   next/script                  -> a <script> tag (how_to scripts)
   NEXT_PUBLIC_*                -> PUBLIC_* in src/env.ts (how_to env); server vars typed there too
+  import 'server-only'         -> keep it (the build honours it). Under bun test the real package throws on
+                                  import, so the scaffold's tests/preload.ts stubs it: bunfig.toml
+                                  [test] preload = ["./tests/preload.ts"], mock.module('server-only', () => ({})).
+                                  A project without those two files adds them before unit-testing an action.
   next-safe-action             -> createActionClient() (how_to action-client); returnValidationErrors -> return fieldErrors({...})
   cache from 'react'           -> cache from @rsc-kit/core/cache: React's dedupes only inside a render; this one
                                   spans the request (guards, actions, api routes). The build names files still on React's
   @react-email/render, renderToString in an action -> the same call, in a module that starts with "use ssr"
+                                  (the build warns naming the app file and the package; the stub throws when called)
                                   (how_to emails). Next gets away with it only for externalised packages; here it is explicit
+  import type { Route } from 'next' -> import type { Route } from '@rsc-kit/core/routes' (pages AND route.ts; a link to a route.ts is an anchor, never prefetched)
 
 DIFFERENT ON PURPOSE
 - No export const dynamic / revalidate = 60. A page is frozen unless it READS
@@ -789,7 +881,10 @@ DIFFERENT ON PURPOSE
   It does not run for actions - the check goes in the action.
 - Actions return failures ({ validationErrors }, { serverError }), not throw.
 - No image optimizer, no opengraph-image.tsx - put opengraph-image.png in src/app.
-- Tests need no browser: createTestApp() is the deployed handler.
+- Tests need no browser: createTestApp() is the deployed handler. It builds
+  with the project's own build script on the runtime the tests run under, and
+  answers files the build wrote to .output/public (assets, sw.js, the
+  manifest, icons) as production does - app.fetch('/sw.js') is a real test.
 - A component library (base-ui, Radix) imports as it did, from server
   components too. A shadcn-style components/ui/ folder keeps "use client" at
   the top of each file, as shipped; without it the server evaluates the
@@ -806,7 +901,40 @@ route that is not ○ names what streams and from which component (a cookies()
 in a layout reaches every page; the build says so) -> decide each action the
 build lists as running no middleware -> check.
 
+CONVERT THE FORMS AND ACTIONS - do not carry them. useActionState +
+useFormStatus, react-hook-form, TanStack Form and useState-per-input all
+still COMPILE here, which is why a port leaves them. Each becomes
+<Form action={…} schema={…}> (how_to forms) and a createActionClient()
+handler (how_to action-client). Remove the form library when the last form
+is converted. A port that keeps two form systems has ported nothing.
+
 Full guide: read_guide({ slug: 'coming-from-next' }).`,
+    },
+    {
+        topic: 'feature-flags',
+        summary: "Vercel's Flags SDK (flags/next) runs unchanged: next/headers is answered by headers()/cookies() here",
+        body: `bun add flags. Then flags/next as written for Next:
+
+  import { flag, dedupe } from 'flags/next'
+  const visitor = dedupe(async ({ cookies, headers }) => ({ id: cookies.get('visitor')?.value ?? 'anon' }))
+  export const showBanner = flag<boolean, { id: string }>({ key: 'show-banner', identify: visitor, decide: ({ entities }) => entities?.id === 'ada' })
+
+  // page.tsx (server component)
+  const on = await showBanner()
+
+The build aliases next/headers to @rsc-kit/core/request - same names, same
+shapes (cookies().get(name)?.value), one object per request, which the SDK's
+dedupe keys on. Nothing to configure, no shim to write.
+
+A flag reads the request, so the page renders per visitor: put a <Suspense>
+or loading.tsx above the read and the build stores the rest as a shell (the
+table says "headers() in run, cookies() in run stream per request").
+
+Discovery endpoint: a route.ts -
+  export const GET = createFlagsDiscoveryEndpoint(async () => getProviderData(flags))
+  export const openapi = false
+precompute() does NOT carry over (it rewrites urls in Next middleware); read
+the flag in the page.`,
     },
     {
         topic: 'emails',
@@ -1015,6 +1143,15 @@ Laravel: composer require rsc-kit/laravel, then php artisan rsc:install. It
 runs rsc-kit init, which writes ONE vite.config.ts (laravel-vite-plugin is
 moved aside - the renderer owns the frontend). Source is resources/js (the route tree is resources/js/app).
 
+rpc() is a global the renderer installs in its own process (never imported,
+never in the browser bundle): one POST to the backend's host-call endpoint
+with { function, args }, the secret and the visitor's cookie; the answer is
+the return value as JSON, typed by rpc<T>(). Refusals arrive as their kind
+(422/401/403/redirect), never a 500; sibling calls in one tick are batched
+and each resolves the moment the backend answers it.
+A BAP server bundle carries no database driver, ORM or auth library - the
+backend owns those.
+
 Reach PHP from a server component - rpc() is a global, typed in
 .rsc-kit/rsc-env.d.ts, server render only:
 
@@ -1031,12 +1168,23 @@ Guard a route in Laravel's vocabulary, no route declared in PHP:
   // resources/js/app/admin/middleware.ts
   export const middleware = ['auth', 'verified', 'can:update,post']
 
+Make one: php artisan make:rsc-action Orders --method=cancel --auth
+--can=update,Order --middleware=throttle:60,1 --revalidate=orders (--rpc for
+an rpc() class under app/Rsc; no --method = invokable). Do NOT hand-write the
+attributes from memory; the command writes the ones the registry reads.
 Server actions are classes in app/Rsc/Actions; \`php artisan
 rsc:action-manifest\` (already in the dev/build scripts) writes the map and
 the build writes server-actions.generated.ts beside the app - import
 ordersCancel from it in a client component. Rsc::revalidate('orders') in the
 action returns the re-rendered region with the answer.
 
+Per url: if the React tree has it, React renders it, otherwise Laravel does
+- including / : the welcome route in routes/web.php answers nothing while
+resources/js/app/page.tsx exists (the package registers the tree's urls from
+bootstrap/rsc/vite/routes.json after routes/web.php). Do NOT tell the user
+to delete the welcome route to make the page show; do not add Laravel routes
+for React pages.
+
 php artisan serve is one worker, which deadlocks the proxy - unless
 PHP_CLI_SERVER_WORKERS=4 in .env AND serve --no-reload (Laravel ignores
 the variable otherwise). Herd, Valet, FPM, Octane are fine as they are. Production: put the renderer in front (bun
@@ -1046,10 +1194,13 @@ the web server.
 Any other language implements the same endpoint - request { function, args },
 reply { result | validationErrors | unauthenticated | unauthorized | redirect
 | error, revalidate }, answers '__rsc.middleware' with true or a refusal, and
-a batch { calls: [...] } with { replies: [{ status, ...reply }] } in order.
-Calls issued in the same render tick travel as one batch, so parallel reads
-are one backend request; the renderer falls back to single calls for a
-backend without batches.
+a batch { calls: [...] } as application/x-ndjson - one line per call AS IT
+FINISHES, { index, status, ...reply }, in any order, flushed each time
+(X-Accel-Buffering: no) - or, less good, one JSON { replies: [...] } in
+order (every call then waits for the slowest). Calls issued in the same
+render tick travel as one batch, so parallel reads are one backend request
+and a fast read still resolves while a slow sibling runs; the renderer falls
+back to single calls for a backend without batches.
 
 Full guides: read_guide({ slug: 'backend-answered-pages' }), read_guide({ slug: 'laravel' }), read_guide({ slug: 'go' }), read_guide({ slug: 'your-own-backend' }).`,
     },
@@ -1080,11 +1231,107 @@ process.env is empty until the first request arrives.
 A scaffolded app with env validation already has this file importing ./env.
 Build machines without production variables: SKIP_ENV_VALIDATION=1.
 
+Never NODE_ENV in a .env: Vite sets it (development under vite, production
+under vite build) and a .env line overrides it for the build, which then
+compiles pages against React's dev JSX runtime (jsxDEV) and every route
+fails with React's opaque "message omitted in production builds". The build
+refuses this and names the file:line. A plugin cannot override it (Vite
+applies the .env value after plugins run), so remove the line - other tools
+that want it keep it in their own .env.
+
 Full guide: read_guide({ slug: 'instrumentation' }).`,
+    },
+    {
+        topic: 'bun',
+        summary: 'Running on Bun - Vite on Bun\'s runtime (bun --bun vite), native deps external (serverExternalPackages), and the gotchas that are Bun\'s not ours',
+        body: `The vite bin has a node shebang: \`bun run dev\` alone starts Vite - dev
+server, build, prerender - under NODE, and an app importing 'bun' or
+'bun:sqlite' fails at first render with "Cannot find package 'bun'". Scripts
+on a Bun app: dev "bun --bun vite", build "bun --bun vite build". createTestApp
+runs the project's build script on the runtime the tests use.
+
+Native dependencies (sharp, bcrypt, better-sqlite3, @prisma/client, puppeteer,
+...) are external to the server bundles by default; Nitro traces them into
+.output/server/node_modules with their binaries. Add one:
+rscKit({ serverExternalPackages: ['@acme/native'] }). Same as Next's option.
+
+The other direction: a dependency with "use client" files that does NOT
+declare react as a peerDependency (generated wrappers, workspace packages
+with react under dependencies) would be left external by plugin-rsc and its
+directive never read - hooks then run on the server. The build detects direct
+dependencies in that state and bundles them, printing
+"[rsc-kit] bundling <pkg>: it has "use client" files but does not declare
+react as a peer dependency". Nothing to configure; fix the package's
+peerDependencies when it is yours.
+
+Bun's, not the framework's: bun test loads the package .env (use
+--env-file=/dev/null to isolate); Stripe's constructEvent throws on Bun
+(no sync WebCrypto) - use constructEventAsync; Bun's pg puts SQLSTATE in
+errno where Node's pg uses code.
+
+Never NODE_ENV in a .env (the build refuses it, naming the line). Build
+machines without secrets: SKIP_ENV_VALIDATION=1.
+
+reflect-metadata (tsyringe, typeorm, inversify - often under
+@simplewebauthn/server): nothing to import; when the graph has it the build
+loads it in a Nitro plugin ahead of the app, so the "tsyringe requires a
+reflect polyfill" boot error does not happen in a directory or a binary.
+
+Build, then start - NEVER run vite build while bun/node .output/server/index.mjs
+is serving from that .output: services load lazily and a failed import of a
+half-written chunk is cached by the runtime (ENOENT 500s until restart).
+
+Single binary (Bun): bun build --compile .output/server/compile.mjs
+--outfile dist/app (the scaffold's "compile" script). compile.mjs is written
+by the build and embeds the frozen pages; with serveStatic: 'inline' in the
+Nitro plugin the assets (and their .br/.gz) are inside too. Ship dist/app
+alone - a Dockerfile copies nothing else, not .output/public.
+
+Nothing is sent raw: a built bun/node server gzips what it answers
+(documents, streams flushed per chunk, payloads, stored pages, api routes)
+for a request that accepts it, and the build writes .br/.gz beside every
+public asset, served by Nitro. Nothing to configure; a Worker leaves it to
+the platform. Off: compress: false on the handler / compressPublicAssets:
+false in Nitro config; Cache-Control: no-transform exempts one answer. Do
+NOT add a compression middleware or precompress assets yourself.
+
+Full guide: read_guide({ slug: 'bun' }).`,
+    },
+    {
+        topic: 'openapi',
+        summary: 'An OpenAPI document derived from route.ts files - rscKit({ openapi }) - and Scalar\'s page over it, mounted as a route',
+        body: `Do NOT hand-write an OpenAPI spec. rscKit({ openapi: true }) in
+vite.config.ts answers /openapi.json, derived from every route.ts: the
+directory is the path ([id] -> {id}), each method export an operation,
+params/searchParams/body schemas the parameters and request body (Zod 4 and
+ArkType describe themselves as JSON Schema; Valibot not yet), a middleware.ts
+above a route a security requirement + 401/403. Stored at build, no middleware.
+
+Document-level parts go on the option:
+  rscKit({ openapi: { info, servers, security, components: { securitySchemes } } })
+What a route says about itself, beside its handler:
+  export const openapi = { summary, tags, responses: { 200: {...} }, POST: { summary } }
+  export const openapi = false   // leave this route out (the reference page, a webhook)
+  export const openapi = { DELETE: false }  // one method out; HEAD/OPTIONS never documented
+Webhook-heavy app: rscKit({ openapi: { include: 'declared' } }) documents only
+routes that export openapi, so callbacks need no opt-out line.
+Response bodies are declared in openapi.responses until a typed helper exists.
+
+The page: Scalar's own package, one route, nothing shipped by the engine:
+  // src/app/reference/route.ts
+  import { ApiReference } from '@scalar/nextjs-api-reference'
+  export const GET = ApiReference({ url: '/openapi.json' })
+  export const openapi = false
+
+Porting a spec file: delete its paths (they are the routes now, and body
+validates at runtime), move info/servers/security to the option, move a
+route's summary/tags/responses to its openapi export.
+
+Full guide: read_guide({ slug: 'openapi' }).`,
     },
     {
         topic: 'env',
-        summary: 'Typed environment variables - src/env.ts with @t3-oss/env-core in the app\'s validation library; refused at startup by name',
+        summary: 'Typed environment variables - src/env.ts with @t3-oss/env-core in the app\'s validation library; refused at startup by name. Never NODE_ENV in .env',
         body: `A scaffolded app has src/env.ts when it said yes to typed environment
 variables (create-rsc-kit --env, with --validation=zod|valibot|arktype). To
 add it to an app without one: install @t3-oss/env-core and write the same file.
@@ -1102,8 +1349,11 @@ export const env = createEnv({
   },
   clientPrefix: 'PUBLIC_',
   client: { PUBLIC_SITE_URL: z.url() },
-  runtimeEnv: { ...process.env, ...import.meta.env },
+  // No bare process.env: a "use client" file importing this for a PUBLIC_
+  // value has no process, and the spread throws before the first render.
+  runtimeEnv: { ...(typeof process === 'undefined' ? {} : process.env), ...import.meta.env },
   emptyStringAsUndefined: true,
+  skipValidation: typeof process !== 'undefined' && !!process.env.SKIP_ENV_VALIDATION,
 })
 \`\`\`
 
@@ -1111,7 +1361,8 @@ Read env.DATABASE_URL, never process.env.DATABASE_URL: the first is typed and
 was checked at startup (a missing or malformed one fails then, with its name),
 the second is string | undefined. A server variable never reaches the browser;
 a browser-readable one MUST start with PUBLIC_ and is read from import.meta.env
-(Vite), which is why runtimeEnv merges both. Commit .env.example, not .env.
+(Vite; the engine registers PUBLIC_ beside VITE_ as a client prefix, nothing
+to configure), which is why runtimeEnv merges both. Commit .env.example, not .env.
 
 Next: NEXT_PUBLIC_* becomes PUBLIC_*; @t3-oss/env-nextjs becomes
 @t3-oss/env-core with runtimeEnv as above (env-nextjs's experimental__runtimeEnv
@@ -1173,6 +1424,10 @@ that stays the truth: a useState, a reducer, or a cache library:
   useEvents<Order>(url, { onMessage: (m) => queryClient.setQueryData(['order', id], m) })  // TanStack
   useEvents<Order>(url, { onMessage: (m) => mutate(['order', id], m, false) })             // SWR
   usePolling(read, { every, onData: setSeats })
+STABLE CALLBACKS: a callback a timer/subscription/listener calls that must see
+the latest props is useEffectEvent from React (19.2+), never a ref assigned
+each render, and never in a dependency array. Both hooks are built on it.
+
 ERRORS: both hooks expose error as state AND fire onError - a failed poll read
 (the next interval still reads) or a dropped stream (EventSource reconnects
 itself). Use onError for a toast/log; do NOT watch error in a useEffect.