@rsc-kit/mcp 0.28.0 → 0.28.1

package/guides/sections.md

@@ -68,613 +68,10 @@ slots the calling page does have.
 
 ## Refreshing on a change from outside
 
-An action can say what it changed because it is the thing changing it. A
-webhook, a job finishing in a worker, another visitor's action - none of
-those is in the tab that is showing the data. For those a section says what
-it depends on, by name:
-
-```tsx title="src/app/t/[team]/repos.section.tsx"
-export default section('repos', Repos, {
-  refreshOn: ({ params }) => [`team:${params.team}:repos`],
-})
-```
-
-and whatever changes the data says so, from wherever it is:
-
-```ts title="src/app/api/github/webhook/route.ts"
-import { changed } from '@rsc-kit/core/changed'
-
-export async function POST(request: Request) {
-  const { team, repos } = await request.json()
-  await saveRepos(team, repos)
-  await changed(`team:${team}:repos`)
-  return new Response(null, { status: 204 })
-}
-```
-
-Every open tab showing the section refreshes it - the same refresh as above,
-with nothing polling and no client code. `refreshOn` is a list of names, or a
-function of the section's props - the page's `params` and `searchParams` -
-that makes them. A page can declare its own with `export const refreshOn`,
-and a change refreshes the page as `refresh('page')` does.
-
-The function is given the page's `params` and `searchParams` already awaited,
-and runs per request, so it can read the request too - a name for the person
-signed in is the usual one on a dashboard:
-
-```tsx title="src/app/dashboard/page.tsx"
-import { cookies } from '@rsc-kit/core/request'
-
-export const refreshOn = async () => [`inbox:${(await cookies()).get('agent')?.value}`]
-```
-
-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
-[`Rsc::changed(…)`](/hosts/laravel#saying-data-changed) - and the page is the same.
-
-### Whose data a name shows
-
-A name is a signal, not data and not a permission. Hearing that
-`conversation:42` changed tells a tab only to ask for its section again; what
-comes back is rendered for that tab's visitor, through their own session, by
-the same queries and guards as the first render. So two people never see each
-other's data through a name - they see whatever their own render shows.
-
-A chat between Ada and Ben:
-
-```tsx title="src/app/chats/[id]/messages.section.tsx"
-export default section('messages', async function Messages({ params }) {
-  const { id } = await params
-  const messages = await rpc('Chats.messages', id)   // the backend checks the viewer is in it
-
-  return <Thread messages={messages} />
-}, { refreshOn: ({ params }) => [`conversation:${params.id}`] })
-```
-
-```tsx title="src/app/inbox/page.tsx"
-// Each person's own list of conversations, with unread counts.
-export const refreshOn = async () => [`inbox:${await currentUserId()}`]
-```
-
-```go
-// Ada sends a message.
-reg.Changed(ctx, "conversation:42", "inbox:"+ben.ID, "inbox:"+ada.ID)
-```
-
-- Both have conversation 42 open, so both tabs refresh it, and each render
-  asks `Chats.messages` as its own visitor. If the thread shows "you" and
-  "them", each sees it from their side.
-- Ben's inbox refreshes; so does Ada's. Nobody else's does: their pages were
-  rendered with their own `inbox:` names.
-- Someone who is not in the conversation cannot open the page - its guards
-  refuse - so no render ever hands them `conversation:42` to listen for. A
-  tab can only listen for names its page was rendered with: the renderer
-  signs them, and a name a browser makes up is refused.
-
-**Name the data, as narrowly as the data.** One name per thing that changes
-together: `conversation:{id}`, `inbox:{userId}`, `team:{id}:repos`. Two
-different things sharing one name only refresh too often; one thing split
-across names refreshes too little. Use ids, not emails or titles - a name
-sits in the page and in the stream's url, and its version says when it last
-changed, so a name must not be something its visitor should not see.
-
-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.
-
-### How a tab finds out
-
-Each name has a version, a number that moves when something says the name
-changed. Nothing else travels - not what changed, not the data.
-
-1. The page renders, reads the version of each name it shows, and hands them
-   to the tab, signed.
-2. The tab opens one stream, `/_rsc/changes`, for every name on the page. Only
-   a page with `refreshOn` opens one, and only while the tab is visible.
-3. The server asks where the versions live - "which of these differ from what
-   I hold?" - once for every open tab it is serving, and again on an interval.
-4. When a version has moved, the stream says so in one line, and the tab asks
-   for exactly the sections showing that name, the way `refresh('repos')` does.
-
-A name belongs to the data, not to a section or a page. Any number of
-sections, on any number of pages, can refresh on the same name: one
-`changed('team:1:repos')` moves its version once, and every open tab showing
-any of them refreshes the ones it has. Section *names* are separate - two
-pages may both have a section called `stats`; each is resolved through its own
-page, and a shared render is never handed from one page to the other.
-
-The data is never pushed: the section is rendered fresh, through its own
-queries and its own guards, as any refresh is. That is also why this runs
-on a Worker - the stream holds no state, and a version is a read.
-
-### Where the versions live
-
-**One server, no backend:** in that server's memory. Nothing to set up - but
-in production rsc-kit says so in its log, once, because the same default
-fails silently the moment there are two instances. If the deploy really is
-one instance, say so and the warning goes:
-
-```ts title="src/instrumentation.ts"
-import { installVersionSource, memoryVersions } from '@rsc-kit/core/changed'
-
-export function register() {
-  installVersionSource(memoryVersions())   // one instance, on purpose
-}
-```
-
-**More than one instance, or a worker process:** this is the case to
-plan for. In-memory versions fail silently the moment a load balancer adds a
-second instance - a change made on one never reaches the tabs held by the
-other - and a job finishes in a process that serves no pages at all. Keep
-the versions somewhere they all share - any database you already have, through
-the client you already use. rsc-kit ships no driver; you hand it yours:
-
-| Your database | The store | Another instance's change arrives |
-| --- | --- | --- |
-| Postgres, with postgres.js or `Bun.sql` (Bun 1.4+) - or the one under Drizzle | `postgresVersions(sql)`, or `postgresVersions(db.$client)` | at once, through LISTEN/NOTIFY; one statement per change |
-| Postgres, with another client | `sqlVersions({ query, placeholder: (n) => '$' + n })` | within a second |
-| MySQL, MariaDB | `sqlVersions({ query, dialect: 'mysql' })` | within a second; one statement per change |
-| SQLite, libSQL, Turso, D1 | `sqlVersions({ query, dialect: 'sqlite' })` | within a second; one statement per change |
-| Redis | `createVersions({ read, bump, listen, notify })` | at once, through pub/sub |
-| An ORM: Drizzle, Prisma, Kysely, Knex | `createVersions` over its query builder, or `sqlVersions` over its raw query | as its database |
-
-`sqlVersions` takes your driver as one function of SQL text and parameters.
-Say which database with `dialect`, and a change is one upsert of every name it
-moves; leave it out and it uses only SQL every database has, a read and a
-write per name:
-
-```ts title="src/versions.ts"
-import { sqlVersions } from '@rsc-kit/core/changed'
-
-// MySQL, mysql2
-export const versions = sqlVersions({ dialect: 'mysql', query: async (text, params) => (await pool.query(text, params))[0] })
-
-// SQLite, bun:sqlite or better-sqlite3
-export const versions = sqlVersions({ dialect: 'sqlite', query: async (text, params) => db.query(text).all(...params) })
-
-// libSQL / Turso
-export const versions = sqlVersions({ dialect: 'sqlite', query: async (sql, args) => (await client.execute({ sql, args })).rows })
-```
-
-and with postgres.js it is one line:
-
-```ts title="src/versions.ts"
-import postgres from 'postgres'
-import { postgresVersions } from '@rsc-kit/core/changed'
-
-export const sql = postgres(process.env.DATABASE_URL!)
-export const versions = postgresVersions(sql)
-```
-
-A SQLite file is shared by the processes on one machine - a web server and a
-worker on the same box. Instances on several machines need a database they
-all reach over the network. The table every one of these reads is described
-[below](#the-table).
-
-postgres.js and `Bun.sql` both LISTEN, and `postgresVersions` uses it when the
-client has it: a change on one instance - or in a worker - reaches the tabs on
-every other at once. A listening server still reads the table now and then, in
-case its listening connection dropped without a word; it is not how changes
-normally arrive.
-
-**Any database, any ORM, or no SQL at all.** rsc-kit needs three things from
-your storage - read some versions, move some versions, and, if it can,
-say the moment one moved - and does the comparing, waiting and waking itself.
-`createVersions` takes exactly those:
-
-With Drizzle, use its query builder rather than raw SQL - the table is one
-more table in your schema:
-
-```ts title="src/db/schema.ts"
-import { bigint, pgTable, text } from 'drizzle-orm/pg-core'
-
-export const rscVersions = pgTable('rsc_versions', {
-  name: text('name').primaryKey(),
-  version: bigint('version', { mode: 'number' }).notNull(),
-})
-```
-
-```ts title="src/versions.ts"
-import { inArray, sql } from 'drizzle-orm'
-import { createVersions } from '@rsc-kit/core/changed'
-import { db } from './db'
-import { rscVersions } from './db/schema'
-
-export const versions = createVersions({
-  read: async (names) =>
-    Object.fromEntries(
-      (await db.select().from(rscVersions).where(inArray(rscVersions.name, names)))
-        .map((row) => [row.name, Number(row.version)]),
-    ),
-  bump: async (names) => {
-    await db.insert(rscVersions)
-      .values(names.map((name) => ({ name, version: Date.now() })))
-      .onConflictDoUpdate({
-        target: rscVersions.name,
-        set: { version: sql`GREATEST(${rscVersions.version} + 1, excluded.version)` },
-      })
-  },
-})
-```
-
-```ts title="Prisma"
-import { sqlVersions } from '@rsc-kit/core/changed'
-
-// Raw SQL through Prisma; the table is a model in its schema - see "The table" below.
-export const versions = sqlVersions({
-  query: (text, params) => prisma.$queryRawUnsafe(text, ...params),
-  placeholder: (n) => '$' + n,   // Postgres; leave out for MySQL and SQLite
-})
-```
-
-```ts title="Redis"
-import { createVersions } from '@rsc-kit/core/changed'
-
-const key = (name: string) => 'rsc:' + name
-const BUMP = `local v = math.max(tonumber(redis.call('GET', KEYS[1]) or '0') + 1, tonumber(ARGV[1]))
-redis.call('SET', KEYS[1], v, 'EX', ARGV[2])
-return v`
-
-export const versions = createVersions({
-  read: async (names) => {
-    const values = await redis.mget(names.map(key))
-    return Object.fromEntries(names.map((name, i) => [name, Number(values[i] ?? 0)]))
-  },
-  // One past where it was, or now if that is larger - see "Cleaning up".
-  bump: async (names) => {
-    await Promise.all(names.map((name) => redis.eval(BUMP, 1, key(name), Date.now(), 30 * 86400)))
-  },
-  // Instant across instances: a subscriber connection hears every bump.
-  listen: (wake) => subscriber.subscribe('rsc:versions', wake),
-  notify: () => redis.publish('rsc:versions', ''),
-})
-```
-
-`sqlVersions({ query })` takes any SQL driver as a function of text and
-parameters - node-postgres, mysql2, Kysely, Knex, D1 - and `createVersions`
-takes anything else.
-
-Install it in every process - the web server once, before the first request.
-`register()` also runs during the build, and that is fine: a store opens no
-connection until a tab is actually waiting on it, and postgres.js connects
-lazily, so a build never holds one open. Keep anything that connects eagerly
-out of `register()`, or the build waits on it and never exits.
-
-
-```ts title="src/instrumentation.ts"
-import { installVersionSource } from '@rsc-kit/core/changed'
-import { versions } from './versions'
-
-export function register() {
-  installVersionSource(versions)
-}
-```
-
-and the worker, which then says what it finished:
-
-```ts title="worker.ts"
-import { changed, installVersionSource } from '@rsc-kit/core/changed'
-import { versions } from './src/versions'
-
-installVersionSource(versions)
-
-queue.on('restoration.done', async (job) => {
-  await changed(`restoration:${job.id}`)
-})
-```
-
-Without `listen` and `notify` - MySQL, SQLite, or a driver that cannot listen -
-a waiting server reads the table every second instead (`poll` changes it).
-
-**From any process, without rsc-kit:** the table is the contract. A cron job,
-a service in another language, a database trigger - anything that can write
-to it can say a name changed:
-
-```sql
--- Postgres
-INSERT INTO rsc_versions (name, version)
-  VALUES ('restoration:42', (EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint)
-  ON CONFLICT (name) DO UPDATE SET version = GREATEST(rsc_versions.version + 1, EXCLUDED.version);
-NOTIFY rsc_versions;   -- optional: wakes the listening servers at once
-
--- MySQL, MariaDB
-INSERT INTO rsc_versions (name, version)
-  VALUES ('restoration:42', FLOOR(UNIX_TIMESTAMP(NOW(3)) * 1000))
-  ON DUPLICATE KEY UPDATE version = GREATEST(version + 1, VALUES(version));
-
--- SQLite
-INSERT INTO rsc_versions (name, version)
-  VALUES ('restoration:42', CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER))
-  ON CONFLICT (name) DO UPDATE SET version = MAX(version + 1, excluded.version);
-```
-
-The new version is one past the old, or the current time in milliseconds if
-that is larger - so a version never repeats, which is what makes it safe to
-delete old rows ([Cleaning up](#cleaning-up)). A writer that still does
-`version + 1` keeps working, since servers only compare; it is only cleanup
-that needs the time. Go's `SQLVersions` uses the same table, so a Go service
-and a JavaScript app can share one.
-
-**LISTEN through an ORM, or another driver.** An ORM builds queries; listening
-is its driver's job, so pass `listen` and `notify` from the client underneath -
-the one you handed the ORM:
-
-```ts title="src/versions.ts"
-import { SQL } from 'bun'
-import { drizzle } from 'drizzle-orm/bun-sql'
-
-const client = new SQL(process.env.DATABASE_URL!)
-export const db = drizzle({ client })
-
-export const versions = createVersions({
-  read,                                                     // the Drizzle read and bump above
-  bump,
-  listen: (wake) => client.listen('rsc_versions', wake),
-  notify: () => client.notify('rsc_versions', ''),
-})
-```
-
-On node-postgres (`pg`), keep one client for listening alone:
-
-```ts
-const listener = new pg.Client(process.env.DATABASE_URL)
-await listener.connect()
-
-listen: async (wake) => {
-  listener.on('notification', wake)
-  await listener.query('LISTEN rsc_versions')
-},
-notify: () => pool.query('NOTIFY rsc_versions'),
-```
-
-A `NOTIFY` sent inside a transaction is only delivered when it commits, so a
-listening tab is never woken before the data it will read is there - the
-[after-commit](#say-it-after-the-write-commits) rule, kept by the database.
-Redis has the same shape with SUBSCRIBE and PUBLISH (the example above).
-
-### The table
-
-A shared store keeps one row per name. Your app owns the table: rsc-kit never
-creates, alters or migrates it at runtime - make it with your own migrations,
-in your own schema, with whatever your ORM calls these types. (Laravel ships
-one you publish into your own migrations, `--tag=rsc-migrations`; after that
-it is yours too.)
-
-| Column | Type | |
-| --- | --- | --- |
-| `name` | text, `PRIMARY KEY` (or a unique index) | the name a section refreshes on |
-| `version` | `BIGINT NOT NULL` | when it last changed, in ms - or one past the last value, if that is larger |
-
-```sql
--- Postgres, SQLite
-CREATE TABLE rsc_versions (name TEXT PRIMARY KEY, version BIGINT NOT NULL);
--- MySQL: an indexed TEXT needs a length
-CREATE TABLE rsc_versions (name VARCHAR(255) PRIMARY KEY, version BIGINT NOT NULL);
-```
-
-- **Extra columns are fine** - an `updated_at`, say - as long as each has a
-  default: rsc-kit and the documented upserts write only `name` and `version`.
-- **Another name is fine:** `sqlVersions({ table })`, `postgresVersions(sql,
-  { table })`, Go's `SQLVersions{Table}`, Laravel's `RSC_VERSIONS_TABLE`.
-- **The NOTIFY channel** is `rsc_versions` whatever the table is called;
-  `postgresVersions(sql, { channel })` changes it.
-- The same table works for Go's `SQLVersions` and Laravel's
-  `RSC_VERSIONS=database`, so a JavaScript app, a Go service and a PHP job
-  can share one.
-
-### Cleaning up
-
-A row is kept for every name that ever changed. For a fixed set of names -
-`team:1:repos` - that is nothing; for one per order, job or restoration it
-grows for ever. Delete the old ones on a schedule:
-
-```ts
-await versions.prune()              // sqlVersions, postgresVersions: not changed in 30 days
-await versions.prune(7 * 86400_000) // or any age, in ms
-```
-
-or from anything that can run SQL - the version is when the name last changed:
-
-```sql
-DELETE FROM rsc_versions WHERE version < (EXTRACT(EPOCH FROM now() - interval '30 days') * 1000)::bigint;
-```
-
-**Deleting is always safe.** A deleted name reads as 0, so a tab still
-holding it sees a different version and refreshes once; changed again, the
-name comes back at the current time - never at a value a tab is holding.
-That is why a bump moves to the time rather than counting: a counter
-restarted at 0 climbs back to values tabs still hold, and they would miss
-the change.
-
-The rest clean up on their own: `memoryVersions()` forgets a name not changed
-in 30 days (`{ forgetAfter }`), the Redis example's keys expire, and the
-server forgets every name the moment no open tab is watching it. Laravel and
-Go have the same: `php artisan rsc:prune-versions` and `SQLVersions.Prune`.
-
-If a store of your own counts with `+ 1`, use `nextVersion(current)` from
-`@rsc-kit/core/changed` instead before you start deleting.
-
-### Say it after the write commits
-
-A tab that hears a name moved asks for its section at once. If the write
-that changed the data has not committed yet, that render reads the old data -
-and the tab is now at the new version, so it will not ask again until the
-next change. Inside a transaction, say it changed **after** the transaction,
-not inside it:
-
-```ts
-await db.transaction(async (tx) => {
-  await tx.insert(conversations).values(row)
-  // not here: this transaction may still roll back, and has not committed
-})
-
-await changed(`agent:${row.agentId}:conversations`)   // here
-```
-
-The same goes for a worker writing the table directly: in the same
-transaction as the data, or after it - never before. In Laravel,
-`DB::afterCommit(fn () => Rsc::changed(...))` does this inside a transaction.
-
-**With a Go or Laravel backend:** the backend keeps them - a table in Go, the
-cache in Laravel - and you install nothing here. The backend owns the data,
-so it answers for its versions too: the renderer asks it which moved, once
-for every tab it is serving. Go holds that question until a version moves,
-so tabs hear at once. PHP cannot hold a request open, so Laravel answers at
-once and is asked again about every two seconds while any tab is watching:
-one small request - a cache read - per renderer process, however many tabs.
-For almost any app that is nothing, and a change reaches the tabs within
-about two seconds - or at once, with Laravel's [broadcasting](/hosts/laravel#saying-data-changed).
-
-### Waking the renderer
-
-Whatever keeps the versions, the renderer has to learn *when* to ask which
-moved. Go holds the question until one does; a store that listens -
-Postgres's LISTEN, Redis's pub/sub - wakes it; otherwise it asks on a timer.
-Anything else that can say "something changed" can wake it too:
-
-```ts title="src/instrumentation.ts"
-import { listenToBroadcast, wakeOn } from '@rsc-kit/core/changed'
-
-export function register() {
-  // A broadcast server - anything speaking the Pusher protocol.
-  wakeOn(listenToBroadcast({ url: process.env.RSC_BROADCAST_URL!, key: process.env.RSC_BROADCAST_KEY! }))
-
-  // Or a Redis channel your backend publishes to.
-  wakeOn((wake) => subscriber.subscribe('rsc:changed', wake))
-}
-```
-
-`RSC_BROADCAST_URL` and `RSC_BROADCAST_KEY` in the renderer's environment do
-the first with no code. A wake carries nothing - no names, no data - so it
-can travel over a public channel: on a wake the renderer asks, as it always
-does, and the versions say which names moved for whom. With something to wake
-it, the renderer asks on its timer only every thirty seconds, as a safety net
-for a dropped connection. Listeners start with the first watching tab, never
-in a build.
-
-**Private data stays private.** A wake decides nothing about who sees what.
-On a wake the renderer asks which of *its tabs'* names moved - names each tab
-got, signed, from its own render - and a tab that has one refreshes its
-section through its own visitor's session and guards. Ada's `inbox:7` is never
-a name Ben's tab holds, so a change to it never refreshes his page, broadcast
-or not. All a public channel shows a subscriber is that the app changed and
-when; if even that timing is sensitive, keep the wake on a channel only the
-renderer can reach - a Redis channel, through `wakeOn` - rather than a
-broadcast.
-
-### The signing secret
-
-The names a page hands the tab are signed, so a tab can only listen for the
-names its page was rendered with - a browser cannot make one up. Every
-instance has to sign with the same key, or a tab served by one is refused by
-the next and never refreshes:
-
-```sh
-RSC_SIGNING_SECRET=… # the same on every instance: openssl rand -base64 32
-```
-
-It is its own secret, with or without a backend - not the backend's
-`RSC_HOST_CALL_SECRET`, which authorises a different thing. In production, an
-app that uses `refreshOn` without it refuses to serve, saying what to set: a
-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'
-
-export function register() {
-  assertSigningSecret()   // throws in production without RSC_SIGNING_SECRET
-}
-``` 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).
-
-Names are signed when the page is served, never at build: a page stored at
-build keeps everything else stored, and the part that carries the names is
-filled per request. So the build does not need the secret.
-
-### When nothing refreshes
-
-In development the browser console says what the page is watching, region
-by region, each time that changes:
-
-```
-[rsc-kit] refreshOn watching, by region:
-  repos: team:1:repos @3
-  page: inbox:ada @0
-```
-
-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
-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.
-
-### When many tabs show the same thing
-
-When a name moves, every tab showing it asks for its sections again - 500 tabs
-on one team's board are 500 renders. Each tab's render can differ by who is
-looking, so by default each is its own. A section that is the same for
-everyone allowed to see the page can say so:
-
-```tsx title="src/app/status/board.section.tsx"
-export default section('board', Board, { refreshOn: ['board'], shared: true })
-```
-
-Then the tabs asking because of the same change get one render between them:
-the first tab's request renders it, and every other gets the same bytes.
-Each tab's guards still run on its own request - a visitor who may not see
-the page is still refused - and only a refresh a change triggered is shared,
-so `refresh()` by hand, or after an action, always renders afresh.
-
-Never set `shared` on a section that shows anything per visitor - their name,
-their data, what they may do. The first tab's render is what every other tab
-is shown, `rpc()` calls included: they run with the first visitor's session.
-
-### What it costs
-
-- **Per tab:** one open connection while the page is visible, closed when the
-  tab is hidden and reopened when it is seen again. Idle, it carries a
-  keepalive line every eight seconds ([set it lower](/hosts/deployment#streams-and-idle-timeouts)
-  under a shorter idle timeout); a change is one line of about forty
-  bytes.
-- **Per change:** each tab showing the name asks for the sections that show
-  it, once, however many names moved together. That request is the size of
-  the section, not the page. A `shared` section renders once per change for
-  every tab; any other renders once per tab.
-- **On the server:** one ask of wherever the versions live, covering every tab
-  that server holds - a thousand open tabs are one query, not a thousand. The
-  ask may wait up to five seconds for a change: a database with `listen`, or a
-  Go backend, answers the moment a version moves; a table without it is read
-  once a second while the ask waits; Laravel answers at once and is asked again
-  two seconds later. Plus one small read when each tab opens its stream.
-
-Polling a section every two seconds instead costs a full render of it, per
-tab, every two seconds, whether anything changed or not. The trade is the open
-connection: cheap on Bun, Node and Workers; on a host that bills a function
-for every second it is open, it is a second billed for as long as the tab is.
-
-### Coming from Next.js
-
-This is where `revalidateTag` was, and it is not the same thing. Next's tags
-label entries in its Data Cache and `revalidateTag()` throws them away, so the
-*next request* refetches; an open tab learns nothing until it navigates.
-There is no data cache here - every render is fresh - so `refreshOn` names
-what is *on screen*, and `changed()` refreshes every open tab showing it, now.
-A port keeps its names: `tags: ['posts']` on the fetch becomes
-`refreshOn: ['posts']` on the section, and `revalidateTag('posts')` becomes
-`changed('posts')`.
-
-A name's version reveals only that something with that name changed. Do not
-put a secret in a name.
+An action refreshes the sections it changed. For a change made anywhere else -
+a webhook, a job, another visitor - a section can name what it depends on and
+refresh itself in every open tab: `section('repos', Repos, { refreshOn })`.
+That has its own guide: [Live data](/guides/live-data).
 
 ## The name is scoped to the module, not the app
 

package/guides/where-it-runs.md

@@ -44,6 +44,14 @@ change:
 nitro({ preset: 'vercel', serveStatic: 'inline' })
 ```
 
+## Streams on serverless platforms
+
+`events()` routes and `refreshOn` hold a connection open. On Workers and
+serverless functions each isolate or instance watches for its own tabs, a
+platform's request limits cut streams (they reconnect and catch up), and
+versions must live in a shared store. [On Workers and serverless](/guides/live-data#on-workers-and-serverless)
+has the details.
+
 ## Running it
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsc-kit/mcp",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "An MCP server over what an rsc-kit build decided: the routes, why each one is static or not, and what it costs the browser.",
   "type": "module",
   "license": "MIT",