@rsc-kit/mcp 0.28.1 → 0.29.0

package/guides/go.md

@@ -272,18 +272,49 @@ reg.Changed(ctx, "team:"+teamID+":repos")
 Every open tab showing the section refreshes it, the moment the webhook
 lands, with nothing polling. The registry answers `__rsc.changed` by holding
 the renderer's ask until a version moves - woken at once by a `Changed` in
-this process, checking the store every `rsckit.TagsPoll` (1s) for one made
+this process, checking the store every `rsckit.ChangedPoll` (1s) for one made
 by another instance.
 
-Versions live in a `TagStore`. The default is in memory, which is one
+Versions live in a `VersionStore`. The default is in memory, which is one
 instance; with more than one, a webhook lands on whichever instance the
 balancer picked, so give them all the same store:
 
 ```go
-// CREATE TABLE rsc_tags (name TEXT PRIMARY KEY, version BIGINT NOT NULL)
-reg.Names(&rsckit.SQLTags{DB: db, Placeholder: rsckit.Dollar})   // Postgres; nil Placeholder is "?"
+// CREATE TABLE rsc_versions (name TEXT PRIMARY KEY, version BIGINT NOT NULL)
+reg.Versions(&rsckit.SQLVersions{DB: db, Placeholder: rsckit.Dollar})   // Postgres; nil Placeholder is "?"
 ```
 
+To hear another instance's change at once instead of within the second - and
+stop reading the store while nothing changes - set `Notify` so each bump
+sends a `pg_notify`, and run a listener with `WakeOn`. The adapter depends on
+no driver, so the listener is yours; with pgx:
+
+```go
+reg.Versions(&rsckit.SQLVersions{DB: db, Placeholder: rsckit.Dollar, Notify: "rsc_versions"})
+
+reg.WakeOn(ctx, func(ctx context.Context, connected, wake func()) error {
+	conn, err := pool.Acquire(ctx)
+	if err != nil {
+		return err
+	}
+	defer conn.Release()
+	if _, err := conn.Exec(ctx, "LISTEN rsc_versions"); err != nil {
+		return err
+	}
+	connected()
+	for {
+		if _, err := conn.Conn().WaitForNotification(ctx); err != nil {
+			return err
+		}
+		wake()
+	}
+})
+```
+
+A listener that drops runs again with backoff, and the poll covers the gap.
+Through PgBouncer in transaction mode, connect the listener straight to
+Postgres. One instance needs none of this.
+
 Anything with a `Bump` and a `Versions` fits. Set `RSC_SIGNING_SECRET` for the renderer, the same on every instance:
 it signs the names a page hands the tab, and is not the host-call secret.
 Generating and rotating both: [Secrets](/hosts/deployment#secrets). [Sections](/guides/live-data)

package/guides/live-data.md

@@ -59,6 +59,21 @@ import { cookies } from '@rsc-kit/core/request'
 export const refreshOn = async () => [`inbox:${(await cookies()).get('agent')?.value}`]
 ```
 
+A page with url schemas types its `refreshOn` from them, so `params` arrives
+parsed and typed rather than typed by hand:
+
+```tsx title="src/app/teams/[team]/page.tsx"
+import type { PageRefreshOn } from '@rsc-kit/core/section'
+
+export const params = z.object({ team: z.string() })
+export const refreshOn: PageRefreshOn<typeof params> = ({ params }) => [`team:${params.team}`]
+```
+
+`export const refreshOn`, `export function refreshOn` and a list -
+`export { refreshOn } from './names'` - all count. `export * from` does not:
+the build reads the page, not what it re-exports wholesale, so name it in a
+list.
+
 That is the whole feature for an app that is only JavaScript. With a Go or
 Laravel backend the backend says it instead -
 [`reg.Changed(ctx, …)`](/hosts/go#saying-data-changed) or
@@ -114,6 +129,55 @@ A section that shows anything per visitor - "you", their unread count, what
 they may do - must never be `shared`: that is the one place a render is
 handed from one visitor to another.
 
+**A change to a child is a change to its parent's list.** Renaming an app
+changes the app's own page and the team's list of apps. Say both where the
+write happens, rather than making either region watch the other's names:
+
+```ts
+await renameApp(app.id, name)
+await changed(`app:${app.id}`, `team:${app.teamId}:apps`)
+```
+
+```tsx
+// The app's page: refreshOn = ({ params }) => [`app:${params.app}`]
+// The team's list: refreshOn = ({ team }) => [`team:${team}:apps`]
+```
+
+Each region names exactly what it shows, and the write - the one place that
+knows what it touched - names everything that did. A region that watched
+every child's name would hand the tab a name per row, and miss a child added
+after it rendered.
+
+**Not everything can announce itself.** A host's runtime logs, a third-party
+status page, anything nothing tells you about: there is no write to call
+`changed()` from, so poll it - `usePolling` - and keep `refreshOn` for data
+your own code changes.
+
+## Testing what a page watches
+
+`createTestApp` renders the page as it is deployed, and `watched()` says what
+each region refreshes on for that url - `page` for the page's own, a
+section's name for each section's:
+
+```ts title="tests/live.test.ts"
+import { createTestApp } from '@rsc-kit/core/testing'
+
+const app = await createTestApp()
+
+test('the team page watches the team and its apps', async () => {
+  expect(await app.watched('/teams/acme')).toEqual({
+    page: ['team:acme'],
+    apps: ['team:acme:apps'],
+  })
+})
+```
+
+A region whose `refreshOn` gave no names is there with `[]` - and said in the
+server's log in development, since that is usually a param read under the
+wrong name. To check what a change does, say it - `changed()` in an app
+that keeps its own versions, `testChanges()` with a test backend - and fetch
+the section again: [What a page watches](/guides/testing#what-a-page-watches).
+
 ## How a tab finds out
 
 Each name has a version, a number that moves when something says the name
@@ -436,7 +500,8 @@ there is no single long-lived process:
 - **Every isolate or instance watches for its own tabs.** Versions in memory
   belong to one isolate, so a `changed()` handled by one never reaches tabs
   held by another. Use a shared store - D1, Postgres, your backend - which the
-  production warning asks for if there is none.
+  production warning asks for if there is none. On Workers, [one hub](#one-hub-on-workers)
+  can hold every tab instead.
 - **Connections are cut.** Platforms bound how long a request may run; a
   stream that is cut reconnects on its own, and the tab catches up from its
   versions. On a platform that bills a function for every second it is open,
@@ -492,6 +557,78 @@ The Cloudflare example's `/live` page is all of this, end to end, and was run
 on `wrangler dev`: a change from its webhook reaches an open tab, and the
 section refreshes with the new value.
 
+### One hub on Workers
+
+Each isolate watches only the tabs it happens to hold, and on Workers that is
+often one. So by default every open tab costs its own ask of the store, every
+two seconds, and a `wakeOn` listener runs once per isolate. A Durable Object
+is one place every isolate can reach. Name it, and every tab's stream goes to
+one instance, which watches all of them:
+
+```ts title="vite.config.ts"
+// cloudflare_module, plus the Durable Object class the hub runs in.
+nitro({ preset: 'cloudflare_durable', serveStatic: 'inline' })
+```
+
+```jsonc title="wrangler.jsonc"
+{
+  "durable_objects": {
+    "bindings": [{ "name": "$DurableObject", "class_name": "$DurableObject" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["$DurableObject"] }],
+  "vars": { "RSC_CHANGES_HUB": "$DurableObject" }
+}
+```
+
+Nothing changes in the app. `RSC_CHANGES_HUB` names the binding, and rsc-kit
+does not look for one on its own: without it, each isolate watches its own
+tabs as before. A name with no binding behind it is said once in the log, and
+the isolate falls back to that.
+
+What changes, against each isolate watching its own tabs:
+
+| | Each isolate (default) | One hub |
+| --- | --- | --- |
+| Asks of the store or backend | one per open tab, every 2s | one for every tab, every 2s |
+| A `changed()` reaches the tabs | at each isolate's next read, within a second or two | at once: `changed()` wakes the hub |
+| A `wakeOn` listener or broadcast | one connection per isolate | one connection |
+| Cost of a store with no LISTEN (D1) | grows with tabs | flat |
+| A Laravel backend | one PHP request per tab, every 2s | one, for every tab |
+
+- **Asks stop growing with tabs.** A thousand open tabs cost the store, or
+  your backend, one ask every two seconds instead of a thousand. On a backend
+  that answers each ask with a PHP request, this is the difference that
+  matters.
+- **Changes arrive at once without LISTEN.** D1 cannot announce a change.
+  With the hub, `changed()` in any isolate - a webhook, an action - pokes the
+  hub after the write, and every tab hears it immediately instead of at the
+  next read.
+- **One listener.** A broadcast server or `wakeOn` listener runs in the hub,
+  one connection for the deployment, rather than one per isolate that
+  happens to hold a tab.
+
+What it costs, and its limits:
+
+- **Durable Object time.** The hub stays active while any tab watches, and a
+  Durable Object is billed for the time it is active - for one instance open
+  all month, a few dollars on Cloudflare's paid plan. With no tab open it
+  costs nothing.
+- **One location.** Every tab's stream goes to the one instance, wherever
+  Cloudflare placed it. An event crosses one more hop, tens of milliseconds;
+  the pages themselves are still rendered by the nearest isolate.
+- **One instance's limits.** A Durable Object runs on one thread, and
+  Cloudflare documents a soft limit of about 1,000 requests a second for
+  one. A site whose tabs connect faster than that should stay on the
+  default flow, which spreads them across isolates.
+- **Versions still live in a shared store.** The hub holds the tabs, not the
+  versions: D1, your database or your backend still keeps them, so a hub that
+  restarts loses nothing.
+
+The forwarded requests carry a proof signed with `RSC_SIGNING_SECRET`, so a
+browser cannot reach the hub's side of the endpoint directly. The Cloudflare
+example runs this way, and was checked on `wrangler dev`: three tabs' streams
+held by the hub, one webhook, and all three hearing the change.
+
 Where a response cannot stream at all, use `usePolling` instead.
 
 ## The table
@@ -643,17 +780,26 @@ random key per instance would fail silently.
 That refusal comes on the first request, because on some platforms - Workers
 - the environment is only there once a request arrives. Under Kubernetes or
 any orchestrator with a readiness check, that is too late: the pod is already
-taking traffic. Make the deploy itself fail instead, from `register()`, which
-runs before the server takes a request:
-
-```ts title="src/instrumentation.ts"
-import { assertSigningSecret } from '@rsc-kit/core/changed'
+taking traffic. Make the deploy itself fail instead, by declaring the secret
+where every other variable is - in `env.ts`, which refuses a missing variable
+before the server starts:
+
+```ts title="src/env.ts"
+export const env = createEnv({
+  server: {
+    // Signs refreshOn's names. Required in production; in development a
+    // random key is fine, and what rsc-kit uses without one.
+    RSC_SIGNING_SECRET:
+      process.env.NODE_ENV === 'production' ? z.string().min(32) : z.string().optional(),
+    // ...
+  },
+  // ...
+})
+```
 
-export function register() {
-  assertSigningSecret()   // throws in production without RSC_SIGNING_SECRET
-}
-``` In development a random key is
-fine, and is what you get.
+An app without an `env.ts` gets the same from `assertSigningSecret()`, from
+`@rsc-kit/core/changed`, called in `register()`. In development a random key
+is fine, and is what you get.
 
 How to generate it, where to keep it, and what rotating it does:
 [Secrets](/hosts/deployment#secrets).
@@ -674,7 +820,8 @@ by region, each time that changes:
 ```
 
 A region that declared `refreshOn` but is missing from that list rendered no
-names, and the server's log says why, once. And watching **stops while the
+names, and the server's log says why, once - including when its function
+returned none at all. And watching **stops while the
 tab is hidden** - a background tab holds no connection - which the console
 also says. Nothing is missed: shown again, the tab reconnects at the versions
 it holds and refreshes whatever moved meanwhile.

package/guides/mcp.md

@@ -76,6 +76,7 @@ it is on the screen.
 
 | tool | answers |
 | --- | --- |
+| `rules` | the rules for this app, as the installed version writes them - read first |
 | `list_topics` | every topic it can explain |
 | `how_to` | the short answer: forms, prefetch, validation, the action client, data with TanStack Query or SWR, Suspense, offline, pwa, no-javascript, api routes, authorization, why a page is dynamic |
 | `list_guides` | every guide on this site, one line each |
@@ -92,6 +93,43 @@ ways that compile either way** — a check written in the component instead of t
 action, a hand-parsed query string, `"use server"` at the top of a page. An
 agent that has not been told writes those confidently.
 
+## The rules an agent follows
+
+`bun create rsc-kit` writes an `AGENTS.md`, and `rsc-kit init` adds a section
+to the one you have. It opens with **Rules** - the things an agent gets wrong
+in ways that compile:
+
+- a change is not done without its test, and not until `check` passes;
+- every environment variable is declared in `env.ts` (and `.env.example`) -
+  rsc-kit's own included;
+- pages paint at once: each read is an async component under its own
+  `<Suspense>`, not a `loading.tsx`;
+- server components call the data function directly, never the app's own api;
+- live data is `refreshOn` with `changed()`, and polling only for what nothing
+  can announce;
+- every action and query is built from the action client the scaffold writes
+  (`src/server/client.ts`), with authorisation as its `.use()` middleware - or,
+  with a Go or Laravel backend, in the backend's own guards;
+- links and redirects are typed template literals; metadata is
+  `export const metadata`;
+- generated files are never edited; secrets are generated, never committed;
+- ask `how_to` before reaching for a pattern from another framework.
+
+The section is rsc-kit's - between `<!-- rsc-kit:start -->` and
+`<!-- rsc-kit:end -->`, stamped with the version that wrote it - and
+everything around it is yours. When rsc-kit changes, bring it up to date:
+
+```sh
+bunx rsc-kit agents     # rewrites the rsc-kit section only; review it in git
+```
+
+The dev server says when the section is older than the rsc-kit installed. An
+`AGENTS.md` from before the stamp needs `--host` and `--source-dir` once; one
+with no section at all is only rewritten with `--replace`. The `rules` tool
+answers the same rules for the installed version, so an agent that reads it
+first is never working from an outdated file. A Laravel app gets the same
+rules from its Boost skill, in Laravel's terms.
+
 ## Two things worth knowing
 
 **Every answer says how old it is.** It reports the last build, and your files

package/guides/testing.md

@@ -177,6 +177,29 @@ above. For the round trip itself, and for anything that depends on hydration —
 `useField` re-rendering, a navigation, an optimistic update reverting — use
 Playwright against `vite preview`, which serves the real build.
 
+## What a page watches
+
+`watched()` renders a page and says what each region refreshes on - `page`
+for the page's own `refreshOn`, a section's name for each section's - without
+reading the signed names out of the payload:
+
+```ts
+expect(await app.watched('/teams/acme')).toEqual({ page: ['team:acme'], apps: ['team:acme:apps'] })
+```
+
+With a Go or Laravel backend stood in by `host`, `testChanges()` answers the
+version questions the way the backend would, and its `changed` says a name
+moved - what the backend's webhook would do:
+
+```ts
+import { createTestApp, testChanges } from '@rsc-kit/core/testing'
+
+const names = testChanges()
+const app = await createTestApp({ host: { ...names.host, 'Repos.list': () => repos } })
+
+names.changed('team:1:repos')
+```
+
 ## What to test where
 
 | what | how |
@@ -186,5 +209,6 @@ Playwright against `vite preview`, which serves the real build.
 | an api route | call `GET`/`POST` with a `Request` |
 | anything that reads cookies or headers | `withRequest()` |
 | routing, guards, stored pages, status codes | `createTestApp().fetch()` |
+| what a page refreshes on | `createTestApp().watched()` |
 | a client component | React + a DOM |
 | an action over the wire, hydration, navigation | Playwright |

package/guides/your-own-backend.md

@@ -66,6 +66,15 @@ 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.
 
+**Arguments that do not fit the function are a failure, not a refusal.**
+Too few, or a value your language cannot decode into the parameter's type:
+answer 500 with `error`, as Go and Laravel do. The renderer's calls are typed
+from your own manifest, so a mismatch is a bug in a caller - most often a
+manifest older than the code - and a 500 is what makes it show up in your
+logs. Extra arguments may be ignored. Values that decode but break your
+rules - an email that is not one - are the input being invalid: a 422 with
+`validationErrors`, below.
+
 **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
@@ -89,7 +98,7 @@ message to tell an invalid form from a broken server:
 | 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) |
+| go somewhere else | **200** | `redirect: "/login"`, and `redirectStatus` when you mean something other than 307 |
 | refused, with its own status | that status | `error`, `refusalStatus: 429` (any 4xx or 5xx: a 503 while a dependency is down) |
 | the function failed | 500 | `error`, and in development `debug` |
 
@@ -100,7 +109,7 @@ and under `""` for a message about the form itself. `unauthenticated` 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
+one. `revalidate` names [sections](/guides/live-data) or `page`, and the answer
 to the action carries the re-rendered region with it rather than the browser
 being told to ask again.
 
@@ -108,7 +117,10 @@ 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.
+it found back to the render as the function's result. The redirect's own
+status goes in `redirectStatus`; without it the renderer uses 307, which keeps
+the method. Send it whenever your framework says something else - Laravel's
+redirects are 302, so the Laravel package always sends it.
 
 **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
@@ -169,11 +181,19 @@ whole-batch form every call in it waits for the slowest.
 
 Either way, run every call 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
-batches at all 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.
+`revalidate` stays with that call. Batches never mix visitors; every call in
+one carried the same forwarded headers.
+
+**At most 50 calls.** The renderer never sends more in one batch; a page with
+more is split. Refusing a larger one - 413, before running anything - is a
+safe limit, and Laravel's.
+
+**Batches are not optional.** The renderer always sends calls from the same
+tick together, and an answer that is neither form - whatever its status -
+fails every call in the batch with what your backend said. None is sent
+again one by one: they may have run, and an action run twice is worse than
+one reported as failed. The conformance suite checks batches, so a backend
+that passes it takes them.
 
 ## Route middleware
 
@@ -222,7 +242,9 @@ an action. Every open tab showing it refreshes, with nothing polling. Two
 things to provide:
 
 **A way to say a name changed**, callable from anywhere in your backend. It
-moves the name's version: a number, kept somewhere every instance of your
+moves the name's version to the larger of one past where it was and the
+current time in milliseconds - so a version never comes round again, and an
+old name can be deleted at any time - kept somewhere every instance of your
 backend shares - a cache, a table - since a webhook lands on whichever
 instance the balancer picked. A name never changed is at 0.
 
@@ -236,7 +258,11 @@ how long it would wait:
 Answer `{ "result": { "versions": { ... } } }` with every name in `since`
 whose version differs now, and nothing else - an empty object when none
 does. If you can, hold the call up to `wait` milliseconds for one to move
-and answer the moment it does: that is what makes the refresh immediate. If
+and answer the moment it does: that is what makes the refresh immediate.
+The renderer asks with 5 seconds; hold no longer than `wait`, and never past
+30 seconds, where the renderer gives up on any call. A name you have never
+seen is at 0, compared like any other: held while the asker also holds 0,
+answered the moment it is changed. If
 you cannot - PHP-FPM, a worker that must answer and go - answer at once; the
 renderer asks again on its interval, a couple of seconds apart. Both are
 conformant, and the page is the same.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsc-kit/mcp",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "An MCP server over what an rsc-kit build decided: the routes, why each one is static or not, and what it costs the browser.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "create-rsc-kit": "^0.29.0",
     "zod": "^3.25"
   },
   "devDependencies": {