@rsc-kit/mcp 0.16.3 → 0.18.0

package/dist/recipes.js

@@ -342,20 +342,40 @@ export default function Page() {
 
 Reach for this first. It is the thing RSC is for.
 
-**When the BROWSER decides to refetch** — a filter, a poll, a refresh — that is
-a cache library's job and this package does not ship one:
+**When the BROWSER decides to refetch** — a filter, another page, a refresh —
+call fetchQuery. It is a plain async function that returns the typed answer;
+NO library is needed:
 
+\`\`\`tsx
+const [listings, setListings] = useState(initial)      // the server-rendered value
+const [pending, start] = useTransition()
+const show = (kind) => start(async () => setListings(await fetchQuery(getListings, [kind])))
+\`\`\`
+Works in an onClick, onSubmit, useEffect - anywhere in the browser.
+
+**When you want CACHING** (stale-while-revalidate, dedupe, offline), hand the
+same call to the library that holds the answer; this package ships none:
 \`\`\`tsx
 useQuery({ queryKey: ['posts', kind], queryFn: () => fetchQuery(getPosts, [kind]) })
 useSWR(['posts', kind], () => fetchQuery(getPosts, [kind]))
 \`\`\`
-
-\`fetchQuery\` sends the read as a GET and goes to the server every time, which
-is what a fetcher needs — staleness and revalidation belong to the library
-holding the answer. Do not add a cache on top of it.
+fetchQuery sends the read as a GET and goes to the server every time, which
+is what a fetcher needs. It will never cache, dedupe or batch: a client
+cache is the library's job, and a batch would lose the per-read cache key a
+GET has. The ladder, most reads stopping on the first rung:
+  1. the value now: fetchQuery + setState
+  2. survive a reload / let a CDN serve it: query(fn, { cache: 'public', maxAge })
+     - HTTP caching, no code in the page
+  3. staleness, background refresh, optimistic updates, shared across
+     components: TanStack or SWR with fetchQuery as the fetcher
+Do not add a cache on top of it, and do not install TanStack for a single
+button that reads once.
 
 Keep the arrow: TanStack calls a bare \`queryFn\` with its own context, and a
-server function serialises whatever it is handed.`,
+server function serialises whatever it is handed.
+
+A value that keeps CHANGING while someone watches - polling, SSE, realtime -
+is how_to live-data, not this.`,
     },
     {
         topic: 'suspense',
@@ -603,7 +623,7 @@ A page's \`params\` and \`searchParams\` props are promises for the same reason.
 The build says which call did it, per route:
 
     ◐  /locale     85 kB
-       dynamic — called cookies(), headers()
+       cookies(), headers() stream per request; the rest is stored
 
 That is usually correct — a page whose content depends on who is asking cannot
 be one stored file. Change it only when the read was accidental.
@@ -747,13 +767,20 @@ IMPORTS
   useParams()                  -> the page's params prop, passed down
   cookies(), headers()         -> same names, from @rsc-kit/core/request
   redirect() / notFound()      -> @rsc-kit/core/redirect / @rsc-kit/core/not-found
-  revalidatePath/Tag           -> revalidate('tag') on a section() - targeted, rides back with the action
+  revalidatePath/Tag           -> revalidate('name') on a section() - targeted, rides back with the action; the
+                                  name is typed to the sections and slots the build found
   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)
   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_*                -> VITE_* via import.meta.env; server vars stay process.env
+  NEXT_PUBLIC_*                -> PUBLIC_* in src/env.ts (how_to env); server vars typed there too
   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"
+                                  (how_to emails). Next gets away with it only for externalised packages; here it is explicit
 
 DIFFERENT ON PURPOSE
 - No export const dynamic / revalidate = 60. A page is frozen unless it READS
@@ -768,11 +795,397 @@ DIFFERENT ON PURPOSE
   the top of each file, as shipped; without it the server evaluates the
   library's internals for nothing.
 
-ORDER: scaffold -> copy src/app -> fix imports -> typecheck -> build and READ
-the output (a cookies() in a layout makes everything dynamic; the build says
-so) -> decide each action the build lists as running no middleware -> check.
+SCAFFOLD FLAGS: --host=bun|node|worker --validation=zod|valibot|arktype|none
+--env/--no-env (typed env vars via @t3-oss/env-core in src/env.ts, in the
+chosen library; server vars never reach the browser, PUBLIC_ prefix for ones
+that may). Pick the library the Next app already uses.
+
+ORDER: scaffold -> copy src/app -> fix imports -> build (it typechecks first,
+so a Link to a route that does not exist fails here) and READ the output: a
+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.
 
 Full guide: read_guide({ slug: 'coming-from-next' }).`,
+    },
+    {
+        topic: 'emails',
+        summary: 'Render React to HTML on the server - an email, a PDF, a feed - from an action or a route, with "use ssr"',
+        body: `@react-email/render, renderToString, anything on react-dom/server, called from
+a server action or a route, fails: "react-dom/server is not supported in React
+Server Components". React means it: where server components render, react is
+the server-only build - the renderer needs the client build's internals, and
+the components it would render import that same react (no useState, no
+useContext). No alias fixes it. The rendering has to run in the ssr
+environment, the one that turns pages into HTML for the browser.
+
+Put the rendering - the template AND the call that renders it - in a module
+that starts with "use ssr". Everything else imports it normally:
+
+\`\`\`tsx
+// src/lib/email/render.tsx
+"use ssr";
+import { render } from '@react-email/render'
+import { OtpEmail } from './otp-email'
+
+export async function renderOtpEmail(code: string) {
+  const email = <OtpEmail code={code} />
+  const [html, text] = await Promise.all([render(email), render(email, { plainText: true })])
+  return { html, text }
+}
+\`\`\`
+
+\`\`\`ts
+// src/lib/email/send-otp.ts - a plain server module, called from the action
+import { renderOtpEmail } from './render'
+export async function sendOtpEmail(to: string, code: string) {
+  const { html, text } = await renderOtpEmail(code)
+  await transporter.sendMail({ to, subject: 'Your code', html, text })
+}
+\`\`\`
+
+Where server components render, the build replaces the module with async
+proxies of its exports that call across - what "use client" does for a
+component, in the other direction. Same process; dev and build; nothing to
+configure.
+
+RULES
+- Exports are async functions. The call crosses environments, so the answer is
+  a promise. A sync function, a value, a class, export { } or export * is
+  refused at build with its name. Types are fine.
+- Pass DATA across, not elements: renderOtpEmail(code), never
+  render(<OtpEmail/>) from the caller. An element built on the calling side
+  carries components from that side's react, and they render with no hooks.
+- The module's imports are the ssr side's: @react-email/components,
+  react-dom/server, a PDF or Markdown renderer. Keep the module to rendering;
+  the database call belongs on the calling side.
+
+Imported react-dom/server directly (through a library, usually)? It now throws
+the fix in its message, naming the app file that pulled it in, and the build
+warns once with the same. Do NOT alias react-dom/server, externalise react, or
+move the action out of the app - the directive is the whole fix.
+
+Full guide: read_guide({ slug: 'emails' }).`,
+    },
+    {
+        topic: 'seo-files',
+        summary: 'robots.txt, sitemap.xml and llms.txt from a file beside the root layout - the shapes Next uses, stored at build when they can be',
+        body: `Files beside the root layout, named for what they answer:
+  src/app/robots.ts    -> /robots.txt    default export returns MetadataRoute.Robots
+  src/app/sitemap.ts   -> /sitemap.xml   default export returns MetadataRoute.Sitemap (an array)
+  src/app/llms.ts      -> /llms.txt      default export returns MetadataRoute.Llms
+  src/app/llms-full.ts -> /llms-full.txt default export returns a string
+The types: import type { MetadataRoute } from '@rsc-kit/core/metadata'. The
+same names and shapes as Next's app/robots.ts and app/sitemap.ts; copy them.
+
+\`\`\`ts
+// src/app/robots.ts
+export default function robots(): MetadataRoute.Robots {
+  return { rules: [{ userAgent: '*', allow: '/', disallow: ['/api/'] }], sitemap: '/sitemap.xml' }
+}
+// src/app/sitemap.ts
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const posts = await db.post.findMany()
+  return [{ url: '/', priority: 1 }, ...posts.map((p) => ({ url: \`/blog/\${p.slug}\`, lastModified: p.updatedAt }))]
+}
+// src/app/llms.ts
+export default function llms(): MetadataRoute.Llms {
+  return { title: 'Acme', summary: 'What it is.', sections: [{ title: 'Pages', links: [{ title: 'Pricing', url: '/pricing' }] }] }
+}
+\`\`\`
+
+A relative url is made absolute with the root layout's metadataBase; without
+one it is a build error. Any of them may return a string, served as written.
+
+NO sitemap.ts? The build writes /sitemap.xml itself: every stored page and
+every generateStaticParams url, lastModified = the build, minus guarded
+routes (middleware.ts above them), failed pages and not-found. Needs the root
+layout's metadataBase. Write sitemap.ts only when you need urls the build
+cannot see or per-url changeFrequency/priority.
+
+HOW FRESH - the function decides, the same rule every route follows:
+  write nothing                        -> the build's own sitemap, stored; fresh every deploy
+  sitemap.ts that reads the database   -> stored at build (○); fresh every deploy
+  sitemap.ts that awaits connection()  -> rendered per request (ƒ); fresh every crawl
+\`\`\`ts
+export default async function sitemap() {
+  await connection()   // from '@rsc-kit/core/request' - per request, like a page
+  return (await db.post.findMany()).map((p) => ({ url: \`/blog/\${p.slug}\`, lastModified: p.updatedAt }))
+}
+\`\`\`
+Reading the database at build is fine; the REQUEST makes it dynamic, not the
+data. Same for robots.ts and llms.ts. No middleware runs for
+them - a root guard must not 401 the crawler. The url is typed
+(route('/sitemap.xml')).
+
+A file as written beside the root layout is served at the root as it is:
+robots.txt, sitemap.xml, sitemap-*.xml, llms.txt, llms-full.txt, humans.txt,
+security.txt, ads.txt. A file and a function for the same url is a build
+error. Do NOT put these in public/ and do NOT write a middleware.ts for them.
+
+Full guide: read_guide({ slug: 'seo-files' }).`,
+    },
+    {
+        topic: 'domains',
+        summary: 'Subdomains and custom domains as route segments - admin.example.com reaches app/admin, a tenant host binds [domain], no rewrite',
+        body: `A request from a host that is not the site's own is matched with the host
+in FRONT of the path. The site's own hosts: the root layout's metadataBase,
+www. of it, and rscKit({ hosts: [...] }) - which is ONLY for a name that is
+neither the apex nor a subdomain of it (a staging/internal name, a second
+brand domain); a normal setup needs no config beyond metadataBase. localhost
+and ips are always own.
+
+  example.com/admin           -> /admin              app/admin/page.tsx
+  admin.example.com/          -> /admin              the same file (subdomain of an own host = its label)
+  acme.example.com/settings   -> /acme/settings      app/[domain]/settings/page.tsx, domain "acme"
+  acme.com/settings           -> /acme.com/settings  the same file, domain "acme.com" (other host = whole host)
+
+The visitor's url is untouched; only the match changes. A top-level [domain]
+binds ONLY from a host, never from a path: example.com/nope is a 404, not a
+tenant called "nope". Otherwise [domain] is an ordinary dynamic segment: params.domain in every page/layout under it, typed
+route('/[domain]/settings', { domain }), loading/error files as usual. A
+directory named for a host (app/admin/) wins over [domain].
+
+\`\`\`tsx
+// src/app/[domain]/layout.tsx
+export default async function TenantLayout({ params, children }) {
+  const { domain } = await params
+  const tenant = await tenantByDomain(domain)   // "acme" or "acme.com", as stored
+  if (!tenant) notFound()
+  return <TenantProvider tenant={tenant}>{children}</TenantProvider>
+}
+// src/app/[domain]/page.tsx - domains in a database: list them, they are stored at build
+export async function generateStaticParams() {
+  return (await db.tenant.findMany()).map((t) => ({ domain: t.domain }))
+}
+\`\`\`
+
+Only when a route could answer it (a top-level [domain] directory, or one
+named for the host); otherwise the host is the site's own. Keep metadataBase as
+the production host: localhost and ips are always own, so dev routes by path.
+To try a tenant locally: curl -H 'X-Forwarded-Host: acme.example.com'
+http://localhost:3000/ (or /etc/hosts). Behind a proxy the
+host is X-Forwarded-Host, then Host. Not for a static export (a file server
+sees no host). Do NOT write a middleware rewrite, do NOT
+read the host in every page - the segment already is the host. The root layout
+needs metadataBase (or rscKit({ hosts })) or every host is the site's own.
+
+Full guide: read_guide({ slug: 'domains' }).`,
+    },
+    {
+        topic: 'identify',
+        summary: 'What a response says about itself - X-RSC-Kit (how it was served, always) and X-Powered-By + a generator tag (what built it, off with identify: false)',
+        body: `Every response carries X-RSC-Kit: stored | rendered | shell - a page from a
+file the build wrote, rendered for this visitor, or a stored shell with its
+holes rendered now. The header to read when a page is slower than expected
+(like X-Nextjs-Cache); a CDN rule or health check can key on it. Names no
+product; always sent.
+
+By default a response also says what built it: X-Powered-By: rsc-kit and
+<meta name="generator" content="rsc-kit"> in every document (BuiltWith,
+Wappalyzer). The NAME only, never the version - a version in every response
+is what a vulnerability scanner filters on.
+
+rscKit({ identify: false }) turns off the name (header and tag) for a policy
+that strips framework identifiers; X-RSC-Kit stays. Do not strip X-RSC-Kit
+at the proxy - it is what tells you whether a stored page was served.
+
+Full guide: read_guide({ slug: 'response-headers' }).`,
+    },
+    {
+        topic: 'backend',
+        summary: 'BAP (Backend-Answered Pages): a Laravel, Go or other backend behind the renderer - rpc() reaches it, middleware.ts names its middleware, app/Rsc/Actions are its server actions',
+        body: `The model is a BAP - Backend-Answered Pages: a page rendered in front of
+the backend rather than by it (MPA: backend renders; SPA: browser renders and
+calls an API; BAP: a renderer on the server renders and calls the backend
+over loopback). The backend is the part that is not a page - models, session,
+auth, policies, jobs - answering one private endpoint, and it keeps every
+route of its own. The whole model, and how to build for it:
+read_guide({ slug: 'backend-answered-pages' }).
+
+Go: in a Go module, rsc-kit init sees go.mod, writes the JS half and .env
+(RSC_BACKEND + a generated secret) and prints the Go wiring; go get
+github.com/rsc-kit/go. A new app: bun create rsc-kit --backend=<url>.
+
+A backend in another language answers that ONE endpoint, POST /__rsc/host-call,
+and the renderer wires itself from two variables in .env: RSC_BACKEND (a
+Laravel app's APP_URL counts) and RSC_HOST_CALL_SECRET. Both or neither.
+
+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).
+
+Reach PHP from a server component - rpc() is a global, typed in
+.rsc-kit/rsc-env.d.ts, server render only:
+
+  // app/Rsc/Orders.php: public function recent(int $limit): array
+  const orders = await rpc<Order[]>('Orders.recent', 5)
+
+The call runs AS THE VISITOR (their cookie is forwarded; auth()->user() is
+them). Refuse with attributes: #[Authenticated], #[Can('update', Order::class)],
+#[Middleware('throttle:60,1')]. A ValidationException lands on the form as
+validationErrors; Authentication/Authorization exceptions answer 401/403.
+
+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']
+
+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.
+
+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
+.output/server/index.mjs with the app's .env), restrict /__rsc/host-call at
+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.
+
+Full guides: read_guide({ slug: 'backend-answered-pages' }), read_guide({ slug: 'laravel' }), read_guide({ slug: 'go' }), read_guide({ slug: 'your-own-backend' }).`,
+    },
+    {
+        topic: 'startup',
+        summary: 'Once-per-process setup - src/instrumentation.ts is imported before any page and its register() awaited before the first request',
+        body: `Setup that belongs to the process - validating env, configuring a shared
+package, warming a connection - goes in src/instrumentation.ts. Do NOT import
+a bootstrap module from pages to get the same effect; it depends on nobody
+forgetting, and the failure is a page throwing "not configured" for whoever
+reaches it first.
+
+  // src/instrumentation.ts
+  import './env'                       // refuses at import -> server fails at startup
+  export async function register() {   // optional; the first render waits for it
+    await db.connect()
+  }
+
+The generated entry imports this file FIRST, so a package configured here is
+configured before any page module evaluates. register() is awaited by every
+entry point (server, dev, prerender, middleware, actions, api routes), once
+per process. On a server it runs at startup and a failure exits the process;
+on a Worker it runs at the isolate's first request.
+
+Worker rule: read bindings INSIDE register(), not at the top of the module -
+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.
+
+Full guide: read_guide({ slug: 'instrumentation' }).`,
+    },
+    {
+        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',
+        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.
+
+\`\`\`ts
+// src/env.ts
+import * as z from 'zod'   // or valibot / arktype - any Standard Schema library
+import { createEnv } from '@t3-oss/env-core'
+
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    DATABASE_URL: z.url(),
+    SESSION_SECRET: z.string().min(1),
+  },
+  clientPrefix: 'PUBLIC_',
+  client: { PUBLIC_SITE_URL: z.url() },
+  runtimeEnv: { ...process.env, ...import.meta.env },
+  emptyStringAsUndefined: true,
+})
+\`\`\`
+
+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.
+
+Next: NEXT_PUBLIC_* becomes PUBLIC_*; @t3-oss/env-nextjs becomes
+@t3-oss/env-core with runtimeEnv as above (env-nextjs's experimental__runtimeEnv
+is not needed).`,
+    },
+    {
+        topic: 'live-data',
+        summary: 'A value that keeps changing - realtime, live updates: usePolling over a query, or server-sent events (SSE, streaming from a middleware.ts generator) with useEvents - both feed TanStack, SWR or setState',
+        body: `Neither is part of query() - a query answers once and is cacheable.
+
+POLLING - start here when you have no change feed yet. Reuses the query,
+goes through its Cache-Control (a CDN collapses many tabs into one origin
+read per interval), pauses when the tab is hidden, never overlaps two reads.
+\`\`\`tsx
+import { usePolling } from '@rsc-kit/core/usePolling'
+const { data, status, refresh } = usePolling(() => fetchQuery(getSeats), { every: 2_000 })
+\`\`\`
+UNTIL IT SETTLES - a job that ends. until(data) says the last read; onSettled
+fires once on it. The result is the DATA; what to
+do on settling is the page's choice:
+  // a server-rendered list, some jobs still running: re-render through the server
+  usePolling(() => fetchQuery(jobStatus, [id]), { every: 2_000, enabled: !isTerminal(job), until: isTerminal, onSettled: () => refresh('page') })
+  // the page that owns the job's state machine: the value in hand
+  const { data, status } = usePolling(read, { every: 1_500, until: isTerminal, onSettled: (f) => dispatch(f.status) })
+Settled = stopped until refresh() or the inputs change. status: 'reading' |
+'paused' | 'settled' | 'idle'.
+
+SERVER-SENT EVENTS - when something can push. Better per update (bytes only
+on change, instant), but holds a connection per open tab (fine on Bun/Node,
+a limit on Workers or a small container), is uncacheable, and needs a source
+of change to yield from - a generator that polls the DB itself just moved the
+polling. An ordinary route.ts: beside its pages, runs middleware.ts above it.
+\`\`\`ts
+// src/app/api/orders/[id]/events/route.ts
+import { events, named } from '@rsc-kit/core/events'
+export const GET = events(async function* ({ params, signal }) {
+  const { id } = await params
+  for await (const status of orderStatus(id, { signal })) yield { status }
+  // yield named('paid', order, { id: order.id }) names a message / gives an id
+})
+\`\`\`
+\`\`\`tsx
+import { useEvents } from '@rsc-kit/core/useEvents'
+const { latest, all, status, close } = useEvents<Status>(\`/api/orders/\${id}/events\`)
+// <Status> is the message type the route yields; a url infers nothing, so
+// without it latest is unknown. Declare the type beside the route, import both sides.
+\`\`\`
+events() frames JSON, sends a keepalive, sets text/event-stream + no-store,
+ends the generator on disconnect (signal). EventSource reconnects itself and
+resumes with Last-Event-ID when you yielded ids.
+
+NO LIBRARY NEEDED. Both hooks ARE state: read data (polling) or latest
+(events) and render it. Neither needs TanStack or SWR.
+  const { latest } = useEvents<Status>(url); const current = latest ?? initial   // the server value until the first message
+WITH A STORE - when the value already lives somewhere, hand every value on so
+that stays the truth: a useState, a reducer, or a cache library:
+  useEvents<Order>(url, { onMessage: setOrder })                                            // useState
+  useEvents<Order>(url, { onMessage: (m) => dispatch({ type: 'update', m }) })              // reducer
+  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 })
+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.
+usePolling's onError gets (error, { failures }) - failed reads in a row, reset
+by a success - so toast on the third, not the first.
+fetchQuery(query, args) types args from the query: fetchQuery(getSeats) for a
+query that takes nothing, fetchQuery(status, [{ id }]) refused if the query's
+input has no id.
+Do NOT put a stream on query() or on a server action, and do NOT poll from
+inside an events() generator.
+
+Full guides: read_guide({ slug: 'queries' }) for polling, read_guide({ slug:
+'api-routes' }) for the streaming route.`,
     },
     {
         topic: 'images',
@@ -802,6 +1215,12 @@ import heroSrc from '../hero.png?w=800&format=webp'
 <img srcSet={hero} src={heroSrc} sizes="(min-width: 800px) 800px, 100vw" width={800} height={600} alt="..." />
 \`\`\`
 
+Declare the query tails in src/images.d.ts, or the build's typecheck stops on
+the imports (a pattern may hold ONE *, so '*?*' matches nothing):
+
+  declare module '*&as=srcset' { const srcset: string; export default srcset }
+  declare module '*&format=webp' { const url: string; export default url }
+
 Hundreds of files in the repo: that is a CDN's job; move them and use unpic.
 An icon or a logo: a plain <img>, or inline the svg.
 
@@ -918,7 +1337,8 @@ export function howTo(topic) {
         // A near miss is common and worth answering rather than refusing: someone
         // asks for "form" or "queries" and means the obvious thing.
         RECIPES.find((r) => r.topic.startsWith(wanted) || wanted.startsWith(r.topic)) ??
-        RECIPES.find((r) => r.summary.toLowerCase().includes(wanted));
+        // The summary is prose, so a multi-word ask is matched with its spaces back.
+        RECIPES.find((r) => r.summary.toLowerCase().replace(/[-\s]+/g, ' ').includes(wanted.replace(/-/g, ' ')));
     if (!found)
         return `No topic "${topic}".\n\n${listTopics()}`;
     return `# ${found.topic} — ${found.summary}\n\n${found.body}`;