@rsc-kit/mcp 0.26.0 → 0.27.1

package/guides/api-routes.md

@@ -215,8 +215,10 @@ export const GET = events(async function* ({ params, signal }) {
 
 An ordinary `route.ts`, so everything above applies: it lives beside its
 pages, runs the `middleware.ts` above it, takes the same params. `events()`
-frames each yield as JSON, sends a keepalive so a proxy does not drop an idle
-stream, sets `text/event-stream` and `no-store`, and ends the generator when
+frames each yield as JSON, sends a keepalive every eight seconds so nothing in
+front drops an idle stream ([`RSC_STREAM_KEEPALIVE_MS`](/hosts/deployment#streams-and-idle-timeouts)
+to change it), sets `text/event-stream` and `no-store, no-transform`, is never
+compressed, and ends the generator when
 the browser goes away — that is what `signal` is for. `named(event, data, {
 id })` names a message or gives it an id, for a client that listens by name or
 resumes after a reconnect.

package/guides/deployment.md

@@ -160,6 +160,75 @@ names the stylesheet and the entry. Nothing to configure, and nothing it
 replaces: the stylesheet still blocks paint, and inlining critical CSS
 stacks on top of it.
 
+## Streams and idle timeouts
+
+An `events()` route and the [`refreshOn`](/guides/sections#refreshing-on-a-change-from-outside)
+stream hold a connection open and are quiet most of the time. Anything in
+front that closes a quiet connection - the server's idle timeout, a proxy's
+read timeout - would cut them, so each sends a keepalive line every **eight
+seconds**: under Bun's default ten, and well under nginx's sixty and
+Cloudflare's hundred.
+
+If something in front closes idle connections sooner, set the keepalive
+below it:
+
+```sh
+RSC_STREAM_KEEPALIVE_MS=4000   # under a 5-second idle timeout
+```
+
+Too long a keepalive does not lose anything - the browser reconnects, and a
+tab catches up on whatever moved - but every open tab is cut and reopens each
+time the timeout passes. Both streams are sent with `Cache-Control: no-store,
+no-transform` and are never compressed, so nothing in front buffers them.
+
+## Secrets
+
+rsc-kit reads up to three. Each is its own key for its own job - never reuse
+one as another, so one leaking does not hand out the rest.
+
+| Variable | What it protects | Who needs it | Read by |
+| --- | --- | --- | --- |
+| `RSC_HOST_CALL_SECRET` | calls between the renderer and a Go or Laravel backend | an app with a backend - required | the renderer **and** the backend |
+| `RSC_SIGNING_SECRET` | the names a page hands a tab for [`refreshOn`](/guides/sections#refreshing-on-a-change-from-outside) | an app that uses `refreshOn` - required in production | the renderer |
+| `RSC_ACTION_ENCRYPTION_KEY` | values a server action sends through the browser, [across a deploy](#server-actions-across-a-deploy) | optional | the renderer, from the build |
+
+`bun create rsc-kit` and `rsc-kit init` generate the first two into `.env` for
+an app with a backend, and `php artisan rsc:install` does the same for
+Laravel. That is development. For production, generate each once and keep it
+where you keep secrets - your platform's environment settings, not the repo:
+
+```sh
+openssl rand -base64 32
+```
+
+or, without openssl:
+
+```sh
+node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+php -r "echo base64_encode(random_bytes(32)), PHP_EOL;"
+```
+
+Three rules apply to all of them:
+
+- **The same value on every instance.** Each is checked by a process that may
+  not be the one that issued it: a tab served by one renderer, a call landing
+  on another backend replica. A value per instance fails for some requests and
+  not others.
+- **At runtime, from the environment.** The built server reads them when it
+  starts, so one build deploys anywhere. `RSC_ACTION_ENCRYPTION_KEY` is the
+  exception: set it at build time too.
+- **Never in git.** The scaffold's `.gitignore` already leaves out `.env`.
+
+**Rotating one** is a deploy, and each says so differently:
+
+- `RSC_HOST_CALL_SECRET` - the renderer and the backend must change together.
+  Between the two, every `rpc()` is refused, so deploy both at once.
+- `RSC_SIGNING_SECRET` - pages already open hold names signed with the old
+  key; their watching is refused and they stop refreshing until reloaded.
+  Nothing else breaks.
+- `RSC_ACTION_ENCRYPTION_KEY` - an action called from a page loaded before the
+  change fails, the same window as a deploy without the key pinned.
+
 ## Pages across a deploy
 
 A page from the previous build asks for a payload from the new one, whose

package/guides/go.md

@@ -34,7 +34,7 @@ server in production:
 
 ```ini title=".env"
 RSC_BACKEND=http://127.0.0.1:8080
-RSC_HOST_CALL_SECRET=a-long-random-string
+RSC_HOST_CALL_SECRET=… # openssl rand -base64 32 - see Secrets under Deployment
 ```
 
 And the endpoint, on whatever mux you already have:
@@ -284,7 +284,9 @@ balancer picked, so give them all the same store:
 reg.Names(&rsckit.SQLTags{DB: db, Placeholder: rsckit.Dollar})   // Postgres; nil Placeholder is "?"
 ```
 
-Anything with a `Bump` and a `Versions` fits. [Sections](/guides/sections#refreshing-on-a-change-from-outside)
+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/sections#refreshing-on-a-change-from-outside)
 has the whole picture.
 
 ## Production

package/guides/laravel.md

@@ -354,7 +354,31 @@ versions live in the cache - the store every server already shares, or the
 one `rsc.tags_store` names; a store that is per server, like `file`, is one
 server's. PHP answers the renderer's ask at once rather than holding it, so
 a change reaches the tab on the renderer's next ask, a couple of seconds
-later. [Sections](/guides/sections#refreshing-on-a-change-from-outside) has the
+later. 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).
+
+**Watching without PHP.** By default the renderer asks PHP which versions
+moved, every couple of seconds while any tab is watching. Keep the versions in
+the `rsc_versions` table instead and the renderer reads them itself:
+
+```sh
+php artisan vendor:publish --tag=rsc-migrations && php artisan migrate
+RSC_VERSIONS=database
+```
+
+```ts title="src/instrumentation.ts"
+import { installVersionSource, postgresVersions } from '@rsc-kit/core/changed'
+import postgres from 'postgres'
+
+export function register() {
+  installVersionSource(postgresVersions(postgres(process.env.DATABASE_URL!)))
+}
+```
+
+Watching then costs PHP no requests, and on Postgres `Rsc::changed()` sends a
+NOTIFY, so tabs hear it at once. On MySQL use `sqlVersions` with your driver;
+the renderer reads the table once a second. [Sections](/guides/sections#refreshing-on-a-change-from-outside) has the
 whole picture.
 
 ## Route middleware

package/guides/sections.md

@@ -69,9 +69,9 @@ 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 landing on the backend, a job finishing, 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:
+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, {
@@ -79,51 +79,455 @@ export default section('repos', Repos, {
 })
 ```
 
-and whatever changes it says so, from wherever it is:
+and whatever changes the data says so, from wherever it is:
 
-```go
-reg.Changed(ctx, "team:"+teamID+":repos")   // Go: in the GitHub webhook handler
+```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 runs per request, so it can read the request - 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.
+
+### 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
+}
 ```
 
-```php
-Rsc::changed("team:$teamId:repos");         // Laravel: a webhook, a job, a listener
+**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` | `postgresVersions(sql)` | at once with postgres.js; within a second with `Bun.sql` |
+| Postgres, with another client | `sqlVersions({ query, placeholder: (n) => '$' + n })` | within a second |
+| MySQL, MariaDB | `sqlVersions({ query })` | within a second |
+| SQLite, libSQL, Turso, D1 | `sqlVersions({ query })` | within a second |
+| 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,
+and writes plain SQL every dialect has - a select, an update, an insert:
+
+```ts title="src/versions.ts"
+import { sqlVersions } from '@rsc-kit/core/changed'
+
+// MySQL, mysql2
+export const versions = sqlVersions({ query: async (text, params) => (await pool.query(text, params))[0] })
+
+// SQLite, bun:sqlite or better-sqlite3
+export const versions = sqlVersions({ query: async (text, params) => db.query(text).all(...params) })
+
+// libSQL / Turso
+export const versions = sqlVersions({ 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 can LISTEN, so a change on one instance reaches the tabs on every
+other at once. `Bun.sql` works too, without LISTEN: a waiting server reads the
+table once a second, so a change from another instance takes up to a second -
+unless a second, listening connection wakes it (below).
+
+**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: 1 })))
+      .onConflictDoUpdate({ target: rscVersions.name, set: { version: sql`${rscVersions.version} + 1` } })
+  },
+})
+```
+
+```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
+
+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)]))
+  },
+  bump: async (names) => { await Promise.all(names.map((name) => redis.incr(key(name)))) },
+  // 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', 1)
+  ON CONFLICT (name) DO UPDATE SET version = rsc_versions.version + 1;
+NOTIFY rsc_versions;   -- optional: wakes the listening servers at once
+
+-- MySQL
+INSERT INTO rsc_versions (name, version) VALUES ('restoration:42', 1)
+  ON DUPLICATE KEY UPDATE version = version + 1;
+
+-- SQLite
+INSERT INTO rsc_versions (name, version) VALUES ('restoration:42', 1)
+  ON CONFLICT (name) DO UPDATE SET version = version + 1;
+```
+
+A version only has to *change*; the servers compare, they do not count. Go's
+`SQLVersions` uses the same table, so a Go service and a JavaScript app can
+share one.
+
+**Instant across instances on a client that cannot LISTEN** - `Bun.sql`, or
+a Drizzle or Prisma setup over one: keep it for reading and writing, and open
+one postgres.js connection only to listen. It costs one idle connection per
+process:
+
+```ts title="src/versions.ts"
+import postgres from 'postgres'
+
+const listener = postgres(process.env.DATABASE_URL!, { max: 1 })
+
+export const versions = createVersions({
+  read,                                                     // as above, on your own client
+  bump,
+  listen: (wake) => listener.listen('rsc_versions', wake),
+  notify: () => listener.notify('rsc_versions', ''),
+})
+```
+
+### 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` | any integer; it only has to change |
+
+```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.
+
+### 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
-import { changed } from '@rsc-kit/core/changed'
-await changed(`team:${team}:repos`)         // no backend: a route.ts, an action
+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
 ```
 
-Every open tab showing the section refreshes it - the same refresh as above,
-with nothing polling. `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.
-
-A name is a name, and that is all that travels. Each has a version, a number
-that moves when something says the name changed. The page learns the versions
-at render; one stream per open tab, opened only on a page with names, watches
-them; a version that moved refreshes exactly the regions holding the name.
-The data is never pushed, which is what lets this run on a host that cannot
-hold state - a version is a read - and the versions live where the backend
-already keeps shared state: Laravel's cache, a table in Go, this process
-when there is no backend. A backend that can hold the question answers the
-moment a name moves; one that cannot, like PHP-FPM, answers at once and is
-asked again a couple of seconds later. The page is the same either way.
-
-**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')`.
-
-Names are authorised by the render: a tab may watch exactly the names its page
-was rendered with, signed by the renderer, so a browser cannot make one up.
-What a name's version reveals is that something with that name changed,
-nothing more - do not put a secret in a name's name.
+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 renderer asks the
+backend which moved: Go holds the question until one does; PHP cannot hold a
+request open, so Laravel is asked again every couple of seconds while any tab
+is watching. To take PHP out of watching altogether, keep Laravel's versions
+in the table (`RSC_VERSIONS=database`) and have the renderer read it itself -
+an app's own store always wins over the backend's:
+
+```ts title="src/instrumentation.ts"
+import { installVersionSource, postgresVersions } from '@rsc-kit/core/changed'
+import postgres from 'postgres'
+
+export function register() {
+  installVersionSource(postgresVersions(postgres(process.env.DATABASE_URL!)))
+}
+```
+
+Watching then costs PHP nothing, and `Rsc::changed()`'s NOTIFY reaches the
+tabs at once.
+
+### 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.
 
 ## The name is scoped to the module, not the app
 

package/guides/your-own-backend.md

@@ -22,7 +22,7 @@ its process environment:
 
 ```ini title=".env"
 RSC_BACKEND=http://127.0.0.1:8080
-RSC_HOST_CALL_SECRET=a-long-random-string
+RSC_HOST_CALL_SECRET=… # openssl rand -base64 32 - see Secrets under Deployment
 ```
 
 `APP_URL` is read where `RSC_BACKEND` is absent, which is what makes a Laravel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsc-kit/mcp",
-  "version": "0.26.0",
+  "version": "0.27.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",