@abide/abide 0.46.0 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # abide
 
+## 0.48.0
+
+### Minor Changes
+
+- 182cdf5: server reads coalesce-only by default, SWR retain client-only ([`98a3e84`](https://github.com/briancray/abide/commit/98a3e84b1e6bdb50b8950a4197ec4a255c560d2a))
+- 182cdf5: warn on a request-scoped ttl>0 read (add shared or drop ttl) ([`b55425c`](https://github.com/briancray/abide/commit/b55425c986fb4c7cebcb1e8c29d1c616466d7d63))
+
+### Patch Changes
+
+- 182cdf5: rename global option/exports/comments to shared ([`1256934`](https://github.com/briancray/abide/commit/125693481ba23152a44375bbe200d575b66fdf9a))
+- 182cdf5: evict outside-request coalesce-only entries; correct shared help copy ([`1b73e21`](https://github.com/briancray/abide/commit/1b73e21c33c8ee985f7109fdedcbe302322ce7d1))
+- 182cdf5: route outside-a-request server reads to the shared store ([`456cfa6`](https://github.com/briancray/abide/commit/456cfa662405714df99545e02ed6e3b851da84df))
+- 182cdf5: Breaking: the `global` cache option is renamed `shared`, and it no longer implies retention. `{ global: true }` (memoise across requests forever) becomes `{ shared: true, ttl: Infinity }` — `shared` now only selects the process store, while `ttl` alone controls retention (default `0` on the server = coalesce-only, `Infinity` on the client). Reads made with no request in flight resolve to the shared store instead of an orphan fallback. ([`d94f0f9`](https://github.com/briancray/abide/commit/d94f0f9cb15a5822b2d5824db7e32da27368fe04))
+
+## 0.47.0
+
+### Minor Changes
+
+- 981c53f: server-side streaming — defineRpc opts.streaming + rewriteForServer injects it ([`00f6fa8`](https://github.com/briancray/abide/commit/00f6fa8fdedc412808108c959c8ad9cced2b643b))
+- 981c53f: socket/rpc instance methods + reactive-surface follow-through ([`0d3d686`](https://github.com/briancray/abide/commit/0d3d686125d7906e1360af4f040f40f39892caa6))
+- 981c53f: on(source, handler) reaction primitive ([`1cfa4f9`](https://github.com/briancray/abide/commit/1cfa4f94bf2e6cd5b612ae26a449007d2b1e1769))
+- 981c53f: syntactic import-resolved reactive recognition (alias-safe, checker-free) ([`1e3e041`](https://github.com/briancray/abide/commit/1e3e041865541058d36c0f5d759d6b09f1256bb4))
+- 981c53f: capture call errors at the boundary, clear on success/invalidate ([`32f3ee7`](https://github.com/briancray/abide/commit/32f3ee7ae495149a7873b5102b215b1d8c07ca04))
+- 981c53f: bare call reads through the cache store (coalesced, reactive) ([`410e552`](https://github.com/briancray/abide/commit/410e552f5b233a814640737954cb01bf5825e816))
+- 981c53f: typed fn.error(args?) probe over the rpc error registry ([`41f4d4a`](https://github.com/briancray/abide/commit/41f4d4a2127a35327bbc573f3656eda9dcf9307a))
+- 981c53f: parked durable writes are pending, not errored ([`41fefbc`](https://github.com/briancray/abide/commit/41fefbc2d4f25c9364bd3e866edb90e1eb82df4e))
+- 981c53f: .refresh/.patch/.peek instance methods ([`55d4051`](https://github.com/briancray/abide/commit/55d40512d6113a20960d128c3d47b5a54d4d6f98))
+- 981c53f: patch() — optimistic/real-time local value mutation ([`67a2df7`](https://github.com/briancray/abide/commit/67a2df733d4e3948e68d253671daf322816737b0))
+- 981c53f: rpc error registry (last error per call identity, reactive) ([`7138e23`](https://github.com/briancray/abide/commit/7138e23bf0285da2f90fdc08e918a4abe3b749ad))
+- 981c53f: export ./ui/state; withdraw scope()/effect from author doc surface ([`77b5221`](https://github.com/briancray/abide/commit/77b52217d5baa9fa22b26d8aba8b0111237434eb))
+- 981c53f: peek() — synchronous non-triggering value probe ([`78469a8`](https://github.com/briancray/abide/commit/78469a89dac0cc014b8958f8e1ffa85e4fb189ba))
+- 981c53f: pre-bound selector methods on rpc instances (pending/refreshing/invalidate/cache) ([`8154dd0`](https://github.com/briancray/abide/commit/8154dd03ca4a1ac1b8c26292a43f72a85f3a9dab))
+- 981c53f: SWR retention always-on for smart reads; type the smart call ([`844a8b7`](https://github.com/briancray/abide/commit/844a8b79a9b526d5d82e5e7febe57f61f23aa98d))
+- 981c53f: done(sub) terminal reader + tail prober reports done/error ([`8a11ab3`](https://github.com/briancray/abide/commit/8a11ab31417edc59f062042b8181e5eaaa6bc140))
+- 981c53f: state() gains .linked/.computed/.share/.shared ([`b02aead`](https://github.com/briancray/abide/commit/b02aeade95173ddea2ea363f6de2f9e1cc23fc90))
+- 981c53f: refresh() — always-refetch over the selector grammar ([`b7bddb2`](https://github.com/briancray/abide/commit/b7bddb2dba94c269449ba2f52193f8c5ace6d5c1))
+- 981c53f: wire client streaming — detectStreaming codegen + proxy flag ([`bac63fe`](https://github.com/briancray/abide/commit/bac63fe94d08a94cbf887600bf2f61764170dbc0))
+- 981c53f: refresh() + peek() ([`d2f8f1a`](https://github.com/briancray/abide/commit/d2f8f1a5f541707a627a9e196ee0b53a060b721a))
+- 981c53f: broadcast() + tail defaults to 1 ([`dc280e9`](https://github.com/briancray/abide/commit/dc280e9e76a781994ee92af8c98967220e4f793e))
+- 981c53f: type-driven streaming — bare call returns Subscribable, drop .stream() ([`f457a2c`](https://github.com/briancray/abide/commit/f457a2c9c716a35ac398217196af92cf5751d650))
+- 981c53f: emit $$watch for bindings; watch recognized + SSR-stripped (renames on) ([`f4f7812`](https://github.com/briancray/abide/commit/f4f781201c82fdfe28d50e5535d93766b0e130c8))
+- c0db71d: Rebuild the data & reactivity surface around one smart call plus thin modifiers/probes/reactions.
+
+    **Breaking changes:**
+
+    - The **bare rpc call is now the smart read** — cached, coalesced, reactive, and stale-while-revalidate by default for replayable (GET/HEAD) reads; writes are coalesce-only. `cache(getFoo, args)` → `getFoo(args)`. The `cache()` function and the `./shared/cache` export are removed (the store remains the internal substrate). Per-call transport options (`signal`/`headers`/`keepalive`/`priority`/`cache`) move to `getFoo.raw(args, init)`; the smart call's second arg is cache/stream options (`ttl`/`tags`/`throttle`/`debounce`/`n`).
+    - **`.refresh` / `.patch` / `.peek`** — new global functions (`./shared/refresh`, `./shared/patch`, `./shared/peek`) and rpc instance methods. `.refresh` replaces `.invalidate` (refetch keeping the stale value visible, never blanking); `.patch` mutates the retained value locally with no network; `.peek` reads the retained value synchronously. `fn.invalidate`/`fn.cache` instance methods are removed (`fn.refresh` / the bare call replace them).
+    - **`watch(source, handler)`** (`./ui/watch`) is the single reaction primitive, replacing `effect`, `socket.on`, and `cache.on` for authors and the compiler (bindings emit `$$watch`). `effect` is off the taught surface (internal plumbing). Instance sugar mirrors the global for the two subscribable/rpc sources — `socket.watch(handler)` and `fn.watch(handler)` / `fn.watch(args, handler)` (client-only; SSR-inert no-op).
+    - **Sockets:** `socket.broadcast(msg)` replaces `.publish`; retention (`tail`) defaults to `1`; `socket.peek()` / `socket.refresh()` added. The `tail()` reactive-consumer function (`./ui/tail`) and `socket.tail()` are off the taught surface — consume the socket directly (`for await` / `watch`) and window via `watch` + `state`; `pending`/`refreshing`/`done`(socket) now register on consumption.
+
+- 2a42d90: Remove all later-hydration: the inferred deferred `{#await cache()}` inert path and the explicit `client:idle` / `client:visible` component islands. Both traded eager hydration for a wake-later heuristic, and the inference was the source of the "control renders dead until the wake fires" bug class. A blocking `{#await cache()}` now renders on the server, seeds warm, and hydrates eagerly — live on the first frame. `client:idle` / `client:visible` are no longer recognized directives. Very large grids that relied on island deferral should adopt their own virtualization.
+- f0f8d77: Close the `<select>` and boolean/numeric binding gaps.
+
+    - **`<select bind:value>` now handles late-mounting options.** Options produced by a `{#for}` block or async data mount _after_ the binding runs, and the browser drops a `value` set that names a not-yet-present option — so the initial value silently failed to apply. The bind now routes through a new `bindSelectValue` runtime helper (`./ui/dom/bindSelectValue`) that re-applies the selection whenever the option set changes (via a `MutationObserver`), covering static, `{#for}`, and async options uniformly.
+    - **`<select multiple bind:value>`** binds an array of the selected option values (two-way): the bound array drives which options are `selected`, and a user's picks are collected back into it.
+    - **SSR selects the matching option.** A server-rendered `<select bind:value>` now emits `selected` on the matching `<option>` (single) or every member (multiple) — the browser ignores a `value="…"` on the select, so the pre-hydration/no-JS state was wrong before. Option value is taken from its `value` attribute, else its static text.
+    - **`<details bind:open>` SSR fix.** `open` is a boolean attribute, so the old generic path emitted `open="false"` and rendered the element _open_ when closed. It now emits the bare attribute only when truthy, like `checked`.
+    - **Numeric input coercion.** `bind:value` on `<input type="number">` / `type="range"` now writes back a number (via `valueAsNumber`, empty field → `undefined`) instead of a string, so number-typed state stays a number.
+
+### Patch Changes
+
+- 981c53f: rpc error registry is client-only — no cross-request SSR leak ([`00c6efb`](https://github.com/briancray/abide/commit/00c6efb0053c0bcd0e44748ebcb85826ec382b27))
+- 981c53f: decide the tool namespace once — mcpTools replaces buildTools/callTool ([`05b31f1`](https://github.com/briancray/abide/commit/05b31f18a02c2ec344f8d17bcbda50d534aad104))
+- 981c53f: migrate .abide fixtures off scope() onto the imported reactive surface ([`0d487db`](https://github.com/briancray/abide/commit/0d487dbf02c6368bd1f889c6679951fc49c364ca))
+- 981c53f: Breaking: re-home subscribable probes onto consume; remove tail() ([`1e0ae9f`](https://github.com/briancray/abide/commit/1e0ae9ff75f2c48921c807c6c4445930933533c6))
+- 981c53f: desugar via import-resolution; bare imported primitives are the surface ([`21a52a5`](https://github.com/briancray/abide/commit/21a52a5b733da810a155eab6863d35b9e9ddd459))
+- 981c53f: keep SSR/client text claims congruent ([`383f7ab`](https://github.com/briancray/abide/commit/383f7ab5582533f7ecaad7c76b01c6ce7c114818))
+- 981c53f: shadow + nested-script recognize imported reactives; effect author-imported ([`415a232`](https://github.com/briancray/abide/commit/415a23223b44ff60776f5f68226d93dc9c2c5c7c))
+- 981c53f: regenerate README + AGENTS.md for the imported-reactive / flat-cache / bare-streaming surface ([`42a7404`](https://github.com/briancray/abide/commit/42a7404c00fa90334d14d715d2a17095f5b5456d))
+- 981c53f: extract finalizeResponse — the dynamic route's wire-handling step ([`4369119`](https://github.com/briancray/abide/commit/4369119ae41e3338af2769790ccd4a2b3cad68de))
+- 981c53f: regenerate README + AGENTS.md for the new data/reactivity surface ([`4c6d6eb`](https://github.com/briancray/abide/commit/4c6d6eb1033f64770c8e2154e856f00f6a5a834f))
+- 981c53f: hoist value consts above __Props so keyof typeof prop annotations resolve ([`581eebe`](https://github.com/briancray/abide/commit/581eebefd41f05d2875f96a3965d90c2c7a1da63))
+- 981c53f: import-resolution is the sole reactive recognition path ([`5b13721`](https://github.com/briancray/abide/commit/5b13721741e5c7bd85844b21f23372b588f05d24))
+- 981c53f: bump scaffold @abide/abide floor to ^0.46.0 ([`5d10cb5`](https://github.com/briancray/abide/commit/5d10cb5b2388fd45e0403b798ca8908b08f0a0e4))
+- 981c53f: reject streaming rpcs at compile time (@deprecated overload → never) ([`7277533`](https://github.com/briancray/abide/commit/7277533c74eec1103c4021844bbb5547f8b452de))
+- 981c53f: narrow the select-bind indexed access so tsgo passes under noUncheckedIndexedAccess ([`796340c`](https://github.com/briancray/abide/commit/796340c5aed2e21a1a46411fda30a4cb9450a95d))
+- 981c53f: resolve full-codebase review findings (22 bugs + cleanups) ([`8523d25`](https://github.com/briancray/abide/commit/8523d25d596d435ffea989ce93da75b4210bb655))
+- 981c53f: server streaming rewrite handles trailing comma / empty opts ([`89eb801`](https://github.com/briancray/abide/commit/89eb80142cae47fc53b3654e0c81f1bd9a394ecc))
+- 981c53f: unify **SSR** payload behind a shared contract + exhaustive boot seed ([`8b242f1`](https://github.com/briancray/abide/commit/8b242f1d0dab035a3bd439370b6a5066d5254d86))
+- 981c53f: sync examples, README, and AGENTS.md to {#snippet} block syntax ([`8fa8e72`](https://github.com/briancray/abide/commit/8fa8e7256eb2ddb1df48ab19c39ebfa1a86ac7c8))
+- 981c53f: repoint scope host to plumbing exports; drop dead reactive imports ([`a58aee6`](https://github.com/briancray/abide/commit/a58aee6418136de675a56190e4b7ee7dc84d54cc))
+- 981c53f: type {#snippet} as Snippet-returning in the check shadow ([`b2bca21`](https://github.com/briancray/abide/commit/b2bca217dfc12a6fe5870bdecf0bca2ef4e4b628))
+- 981c53f: Breaking: flatten cache(fn, args, options) — direct read-through, drop the wrapper ([`b8d356f`](https://github.com/briancray/abide/commit/b8d356fb078a548433311dd19a2bec930c30e29a))
+- 981c53f: migrate template + scaffold to the new surface ([`bc1ccfd`](https://github.com/briancray/abide/commit/bc1ccfdc7699cc0de034bdadcf79b7cc5e3695bd))
+- 981c53f: guard detectStreaming indexed access under noUncheckedIndexedAccess ([`bc5cecb`](https://github.com/briancray/abide/commit/bc5cecbf5b6669297a90e16cf8762110b928b641))
+- 981c53f: one module per resolved runtime value — the slot is the seam ([`c2dcde4`](https://github.com/briancray/abide/commit/c2dcde496e43868aeb94c23773e9f6630820b3c9))
+- 981c53f: declare pending/refreshing/invalidate/cache instance methods ([`c743df8`](https://github.com/briancray/abide/commit/c743df80777f6dcf1c7d326713c6124254a4bca4))
+- 981c53f: record why the type-check shadow stays off the Plan model (ADR-0014) ([`c9f77dd`](https://github.com/briancray/abide/commit/c9f77ddb44832354e71d711d035be497fa258ef6))
+- 981c53f: flatten cache() and update .stream() doc to bare streaming-rpc call ([`cfdf715`](https://github.com/briancray/abide/commit/cfdf71546bf14c2e29714d057307b14081e048a9))
+- 981c53f: Breaking: remove .invalidate/.cache instance methods ([`e809b22`](https://github.com/briancray/abide/commit/e809b22280ff851e51dbbbc3e65c6e8e6fb86a81))
+- 981c53f: Breaking: remove ./shared/cache export; retag ./ui/effect as plumbing ([`e9b5e94`](https://github.com/briancray/abide/commit/e9b5e9463f6f201bbf7e7b9455e5090e4c4c6ba6))
+- 981c53f: fold route matching into shared matchRoute ([`f00630b`](https://github.com/briancray/abide/commit/f00630bd2366f968e412d61b7b791e679d985414))
+- 981c53f: Breaking: remove .publish, migrate all call sites to .broadcast ([`fa0fd00`](https://github.com/briancray/abide/commit/fa0fd00f5f891d9f804155aaf496f6cf0eb9c535))
+
 ## 0.46.0
 
 ### Minor Changes

package/README.md

@@ -1,242 +1,277 @@
 # abide
 
-**One typed declaration fans out to HTTP, a CLI, an MCP tool, and an OpenAPI
-spec — on a single Bun runtime.**
+**One typed declaration, every surface: an RPC you write once fans out to HTTP,
+a CLI, an MCP tool, and an OpenAPI operation — and the same callable runs
+in-process on the server and over fetch in the browser.**
 
-abide is a type-safe isomorphic framework: you declare an RPC, a socket, and a
-`.abide` component once, and the bundler swaps the runtime per side — the same
-callable is a direct in-process call on the server and a typed `fetch` in the
-browser. Built for humans *and* machines: every schema-carrying RPC is
-simultaneously a browser endpoint, a CLI subcommand, an MCP tool, and an
-OpenAPI operation.
+abide is an isomorphic multimodal HTTP framework built for humans and machines
+in a single Bun runtime: file-path routing, Standard Schema validation, and a
+compiled `.abide` UI layer that server-renders, streams, and hydrates the same
+components. The bundler swaps each callable's runtime per side — same name,
+same behavior, no client/server forks in app code.
 
-One direct dependency (TypeScript). One runtime (Bun ≥ 1.3.0).
+- One direct dependency (TypeScript). One runtime (Bun ≥ 1.3).
 
 ## Quick start
 
 ```sh
-# Scaffold a project, install it, and start the dev server (in a TTY).
-bunx abide scaffold my-app
+bunx abide scaffold my-app   # scaffolds, installs, and starts the dev server
+```
+
+Or run the kitchen-sink example, which demos the full surface:
 
-# Or explore the full feature set in the kitchen-sink example.
+```sh
 git clone https://github.com/briancray/abide
-cd abide/examples/kitchen-sink
-bun install
-bun run dev
+cd abide && bun install
+cd examples/kitchen-sink && bun run dev
 ```
 
 ## RPCs
 
-An RPC is one export per file under `src/server/rpc/`. The file path is the URL
-(under `/rpc/`), the import (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`HEAD`) picks
-the HTTP method, and an optional `inputSchema` — any Standard Schema (zod,
-valibot, arktype, unadapted) — validates the args and projects the MCP tool, the
-CLI flags, and the OpenAPI operation.
+An RPC is one exported handler per file under `src/server/rpc/` — the file path
+is the URL. The export wraps the handler in an HTTP-method helper (`GET`,
+`POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`); a Standard Schema `inputSchema`
+(zod, valibot, arktype — no adapter) validates the args and projects the CLI
+flags, the MCP tool, and the OpenAPI operation from the one declaration.
 
 ```ts
 // src/server/rpc/getMessages.ts
 import { GET } from '@abide/abide/server/GET'
 import { json } from '@abide/abide/server/json'
 import { z } from 'zod'
+import { listMessages } from '$server/store'
 
-const rooms: Record<string, { id: string; text: string }[]> = {}
-
-// GET /rpc/getMessages?room=lobby
 export const getMessages = GET(
-    (args: { room: string }) => json(rooms[args.room] ?? []),
-    { inputSchema: z.object({ room: z.coerce.string() }) },
-)
-```
-
-```ts
-// src/server/rpc/postMessage.ts
-import { POST } from '@abide/abide/server/POST'
-import { json } from '@abide/abide/server/json'
-import { error } from '@abide/abide/server/error'
-import { z } from 'zod'
-
-const rateLimited = error.typed('rateLimited', 429)
-
-// A mutating method never auto-exposes to MCP — opt in explicitly.
-export const postMessage = POST(
-    (args: { room: string; text: string }) => {
-        if (args.text.length > 500) return rateLimited()
-        return json({ ok: true })
+    async ({ room, limit }) => json(await listMessages(room, limit)),
+    {
+        inputSchema: z.object({
+            room: z.string(),
+            limit: z.coerce.number().default(50),
+        }),
     },
-    { inputSchema: z.object({ room: z.string(), text: z.string() }), clients: { mcp: true } },
 )
 ```
 
-One declaration, five surfaces:
+That one file fans out:
 
 ```text
-              export const getMessages = GET(fn, { inputSchema })
-                                  │
-      ┌────────────┬─────────────┼─────────────┬────────────┐
-      ▼            ▼             ▼             ▼            ▼
- cache(fn)()   typed fetch    MCP tool     CLI subcmd   OpenAPI op
-  (SSR, warm    (browser,    (read-only   (any schema-  (/openapi
-   hydration)    swapped)     GET/HEAD)    carrying)     .json)
+src/server/rpc/getMessages.ts
+      │
+      ├─ SSR / server   await getMessages({ room })  in-process, no HTTP
+      ├─ browser        await getMessages({ room })   typed fetch proxy
+      ├─ HTTP           GET /rpc/getMessages?room=…
+      ├─ CLI            my-app get-messages --room …
+      ├─ MCP            tool: get-messages
+      └─ OpenAPI        operation in /openapi.json
 ```
 
-A schema unlocks the CLI for any RPC and MCP for read-only methods (`GET`/`HEAD`);
-a mutating method (`POST`/`PUT`/`PATCH`/`DELETE`) reaches MCP only with an
-explicit `clients: { mcp: true }`. Consume an RPC four ways: `cache(fn)()`
-in-process (warm SSR + hydration), the swapped `fetch` in the browser,
-`fn.raw(args)` for the underlying `Response`, and `fn.stream(args)` to iterate
-`jsonl`/`sse` frames.
-
-> Query args travel as strings — coerce them (`z.coerce.number()`). A per-RPC
-> `timeout` returns 504 on every surface; it is distinct from the client-wide
-> `ABIDE_CLIENT_TIMEOUT`.
+A schema is the gate: it unlocks the CLI, and — for read-only methods
+(GET/HEAD) — the MCP tool. A mutating method (POST/PUT/PATCH/DELETE) never
+auto-exposes to MCP; it needs an explicit `clients: { mcp: true }`.
+
+The bare call **is** the smart read — cached, coalesced, reactive,
+stale-while-revalidate — and it is isomorphic: the same callable resolves
+in-process during SSR (its value baked into the HTML for warm hydration) and
+over `fetch` in the browser. Around it:
+
+- `getMessages.raw(args, init?)` — the raw `Response`; per-call transport
+  options (`signal`, `headers`, …) live here
+- `getMessages.refresh(args?)` — refetch, keeping the stale value visible
+- `getMessages.patch(args?, updater)` — mutate the retained value locally,
+  no network
+- `getMessages.peek(args?)` — read the retained value synchronously
+- `getMessages.pending(args?)` / `.refreshing(args?)` / `.error(args?)` —
+  reactive probes
+- a handler that returns `jsonl()`/`sse()` makes the bare call return a
+  `Subscribable` you `for await` — detected at build time, nothing to declare
+
+> Query args travel as strings — use `z.coerce.*` for numbers and booleans on
+> GET/HEAD. The per-RPC `timeout` option is a server-side handler deadline
+> (504, enforced on every surface); `ABIDE_CLIENT_TIMEOUT` bounds browser calls
+> and is separate.
 
 ## Sockets
 
-A socket is one broadcast topic per file under `src/server/sockets/`. A
-`Socket<T>` is an isomorphic `AsyncIterable<T>` — iterate for the live stream,
-`.tail(count)` to seed from the retained tail. Every socket multiplexes onto one
-WebSocket at `/__abide/sockets`; the server publishes in-process and fans out,
-the browser proxy sends a `pub` frame.
+A socket is one broadcast topic per file under `src/server/sockets/` — the
+export name is the topic. A `Socket<T>` is an isomorphic `AsyncIterable<T>`:
+server code iterates and broadcasts in-process; browser code gets the same
+shape over one multiplexed WebSocket at `/__abide/sockets`.
 
 ```ts
-// src/server/sockets/messages.ts
+// src/server/sockets/chat.ts
 import { socket } from '@abide/abide/server/socket'
 import { z } from 'zod'
 
-export const messages = socket({
-    schema: z.object({ room: z.string(), text: z.string() }),
-    tail: 50, // retain the last 50 frames for late joiners / reconnects
-    ttl: 60_000, // evict retained frames older than 60s before replay
+export const chat = socket({
+    schema: z.object({ author: z.string(), text: z.string() }),
+    tail: 50, // retain the last 50 frames for late joiners (default 1)
+    ttl: 60_000, // retained frames expire after a minute
+    clientPublish: true, // allow browser publishes (off by default)
 })
 ```
 
-The HTTP face lives at `/__abide/sockets/<name>`: `GET` returns the retained
-tail, `POST` publishes (gated by `clientPublish`).
+`chat.broadcast(msg)` publishes from either side — schema-validated on the
+server, and client publishes are gated by `clientPublish`. `for await (const
+msg of chat)` is the live stream; `chat.peek()` reads the latest retained
+frame; `chat.refresh()` re-pulls the server tail after a reconnect. A schema
+also advertises the topic to MCP and the CLI.
+
+Every exposed socket has an HTTP face at `/__abide/sockets/<name>`: `GET`
+returns the retained tail as JSON (or a live SSE stream under
+`Accept: text/event-stream`), `POST` publishes — gated by `clientPublish`.
 
 ## Components
 
-A `.abide` component is a single file: a leading `<script>` (module imports plus
-reactive setup), the template, and an optional component-scoped `<style>`. This
-page imports the RPC from §RPCs and the socket from §Sockets and drives them
-through the whole template grammar.
+Pages are `.abide` single-file components under `src/ui/pages/` (`page.abide` /
+`layout.abide`; a `[id]` folder becomes a route param read via `props()`). A
+component is HTML plus `{expr}` bindings and `{#…}` control-flow blocks.
+Reactive state comes from imported primitives the compiler lowers, so inside a
+component you read and write state as plain variables. The same file renders on
+the server — blocking awaits inline, streaming awaits out of order, cached
+reads seeded warm — and hydrates in the browser.
 
-Reactive state is reached only through `scope()`. The authoring default is the
-destructure-once idiom — pull the primitives off `scope()` at the top of the
-`<script>`, then call them bare. `computed` is read-only; `effect` is client-only
-(stripped from SSR). A bare `state`/`computed`/`linked`/`effect` with no
-`scope()` destructure is a compile error.
+A child component renders whatever you nest in it at `{children()}`:
 
 ```html
 <script>
-import { cache } from '@abide/abide/shared/cache'
-import { tail } from '@abide/abide/ui/tail'
-import { html } from '@abide/abide/ui/html'
-import { getMessages } from '$server/rpc/getMessages.ts'
-import { postMessage } from '$server/rpc/postMessage.ts'
-import { messages } from '$server/sockets/messages.ts'
-import MessageCard from '$ui/MessageCard.abide'
-
-const { state, computed, linked, effect } = scope()
-const { room = 'lobby' } = props()
-
-let draft = state('')
-let showRaw = state(false)
-let filter = state('all')
-const trimmed = computed(() => draft.trim())
-const outgoing = linked(() => room + ': ' + trimmed)
-const banner = html`<strong>#${room}</strong>`
-
-// client-only reaction — never runs during SSR
-effect(() => console.log('draft is now', draft))
-
-// the derived two-way binding target, read down / written up
-const get = () => outgoing
-const set = (value) => (draft = value)
-// mutating RPC from an event handler
-const send = () => {
-    postMessage({ room, text: trimmed })
-    draft = ''
-}
+    const { title } = props()
 </script>
 
-{#snippet chip(label)}
-    <span class="rounded bg-slate-100 px-2 text-xs">{label}</span>
+<section>
+    <h2>{title}</h2>
+    {#if children}{children()}{:else}<p>Nothing here yet.</p>{/if}
+</section>
+
+<style>
+    section {
+        border: 1px solid gray;
+    }
+</style>
+```
+
+And one page tying together the RPC from above, the socket, and the whole
+template grammar:
+
+```html
+<script>
+    import { getMessages } from '$server/rpc/getMessages'
+    import { sendMessage } from '$server/rpc/sendMessage' // POST, declared like getMessages
+    import { chat } from '$server/sockets/chat'
+    import { state } from '@abide/abide/ui/state'
+    import { watch } from '@abide/abide/ui/watch'
+    import { html } from '@abide/abide/ui/html'
+    import Panel from '$ui/components/Panel.abide'
+
+    const { room = 'lobby' } = props()
+
+    let draft = state('')
+    let author = state('anon')
+    let tone = state('friendly')
+    let notify = state(true)
+    let volume = state(5, (next, previous) => (Number.isFinite(next) ? next : previous))
+    let shout = state.computed(() => draft.toUpperCase())
+    let roomDraft = state.linked(() => room)
+
+    // watch is the one reaction primitive: a socket, an rpc, or a tracked thunk.
+    watch(chat, () => getMessages.refresh({ room }))
+    watch(() => console.log(author, tone))
+
+    // a writable computed lives at the binding: bind:value={{ get, set }}
+    const get = () => draft.trim()
+    const set = (next) => (draft = next)
+
+    const focus = (element) => element.focus()
+    const panelProps = { title: 'Live feed' }
+    const draftAttrs = { placeholder: 'say something', autocomplete: 'off' }
+
+    async function send() {
+        await sendMessage({ room: roomDraft, author, text: draft })
+        draft = ''
+    }
+</script>
+
+{#snippet line(message)}
+    <li>{message.author}: {message.text}</li>
 {/snippet}
 
-<section class="p-4" attach={(node) => node.focus()} {...{ id: 'chat' }}>
-    <h1 class:live={showRaw} style:opacity={showRaw ? 1 : 0.6}>{banner}</h1>
+<Panel {...panelProps}>
+    <h1 class:muted={!notify} style:opacity={notify ? '1' : '0.6'}>
+        {room} — {shout}
+    </h1>
 
-    {#await cache(getMessages)({ room })}
+    {#await getMessages({ room })}
         <p>loading…</p>
-    {:then history}
-        {#if history.length > 0}
-            {#for message, i of history by message.id}
-                <MessageCard {...message}>
-                    {chip(i)}
-                    <p>{message.text}</p>
-                </MessageCard>
-            {/for}
-        {:else if showRaw}
-            <p>no history yet</p>
+    {:then messages}
+        {#if messages.length === 0}
+            <p>No messages yet.</p>
+        {:else if messages.length < 100}
+            <ul>
+                {#for message, i of messages by message.id}
+                    {line(message)}
+                {/for}
+            </ul>
         {:else}
-            <p>say hello</p>
+            <script>
+                // branch-local state, re-seeded each time this branch mounts
+                let offset = state(0)
+            </script>
+            <p>huge room — showing from {offset}</p>
+            <button onclick={() => (offset = offset + 100)}>next</button>
+            <style>
+                p {
+                    font-variant-numeric: tabular-nums;
+                }
+            </style>
         {/if}
     {:catch error}
         <p>failed to load: {error.message}</p>
     {:finally}
-        <hr />
+        <p>checked just now</p>
     {/await}
 
-    {#for await frame of messages.tail(10)}
-        <p class="live-frame">{frame.text}</p>
-    {/for}
-
-    {#switch filter}
-        {:case 'all'}<p>showing all rooms</p>
-        {:case 'mine'}<p>showing my rooms</p>
-        {:default}<p>—</p>
+    <ol>
+        {#for await message of chat}
+            {line(message)}
+        {/for}
+    </ol>
+
+    {#switch tone}
+        {:case 'friendly'}
+            <p>{html`<em>be&nbsp;kind</em>`}</p>
+        {:default}
+            <p>say anything</p>
     {/switch}
 
     {#try}
-        {#if showRaw}
-            <script>const { computed } = scope()
-const label = computed(() => 'raw view active')</script>
-            <pre>{label}</pre>
-        {/if}
-    {:catch error}
-        <p>render error: {error.message}</p>
-    {:finally}
-        <small>rendered</small>
+        <p>{JSON.parse(draft).summary}</p>
+    {:catch}
+        <p>draft isn't JSON yet</p>
     {/try}
 
-    <form onsubmit={send}>
-        <input bind:value={draft} placeholder="message" />
-        <label><input type="checkbox" bind:checked={showRaw} /> raw</label>
-        <label><input type="radio" bind:group={filter} value="all" /> all</label>
-        <label><input type="radio" bind:group={filter} value="mine" /> mine</label>
+    <form onsubmit={(event) => { event.preventDefault(); send() }}>
+        <input attach={focus} bind:value={draft} {...draftAttrs} />
         <input bind:value={{ get, set }} />
-        <button type="submit">send</button>
+        <label><input type="checkbox" bind:checked={notify} /> notify</label>
+        <label><input type="radio" bind:group={tone} value="friendly" /> friendly</label>
+        <label><input type="radio" bind:group={tone} value="blunt" /> blunt</label>
+        <input type="range" bind:value={volume} min="0" max="10" />
+        <select bind:value={author}>
+            <option>anon</option>
+            <option>me</option>
+        </select>
+        <button disabled={draft === ''}>send</button>
     </form>
-</section>
+</Panel>
 
 <style>
-    .live { color: teal; }
+    form {
+        display: flex;
+        gap: 0.5rem;
+    }
+    .muted {
+        color: gray;
+    }
 </style>
 ```
 
-Content nested inside a capitalised child component renders where the child
-calls `{children()}` — the single slot, with `{#if children}…{:else}…{/if}` as
-its fallback (there is no `<slot>` element and no named slots):
-
-```html
-<script>
-const { text = '' } = props()
-</script>
-
-<article class="card rounded border p-2">
-    <p class="font-medium">{text}</p>
-    {#if children}{children()}{:else}<em>no body</em>{/if}
-</article>
-```
-
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.46.0",
+    "version": "0.48.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -46,7 +46,6 @@
         "./server/error": "./src/lib/server/error.ts",
         "./server/redirect": "./src/lib/server/redirect.ts",
         "./server/request": "./src/lib/server/request.ts",
-        "./server/reachable": "./src/lib/server/reachable.ts",
         "./server/cookies": "./src/lib/server/cookies.ts",
         "./server/env": "./src/lib/server/env.ts",
         "./server/appDataDir": "./src/lib/server/appDataDir.ts",
@@ -57,10 +56,13 @@
         "./server/rpc/defineRpc": "./src/lib/server/rpc/defineRpc.ts",
         "./server/sockets/defineSocket": "./src/lib/server/sockets/defineSocket.ts",
         "./server/prompts/definePrompt": "./src/lib/server/prompts/definePrompt.ts",
-        "./ui/tail": "./src/lib/ui/tail.ts",
-        "./shared/cache": "./src/lib/shared/cache.ts",
+        "./ui/watch": "./src/lib/ui/watch.ts",
         "./shared/pending": "./src/lib/shared/pending.ts",
+        "./shared/patch": "./src/lib/shared/patch.ts",
+        "./shared/peek": "./src/lib/shared/peek.ts",
+        "./shared/refresh": "./src/lib/shared/refresh.ts",
         "./shared/refreshing": "./src/lib/shared/refreshing.ts",
+        "./shared/done": "./src/lib/shared/done.ts",
         "./shared/HttpError": "./src/lib/shared/HttpError.ts",
         "./shared/ValidationErrorData": "./src/lib/shared/types/ValidationErrorData.ts",
         "./shared/snippet": "./src/lib/shared/snippet.ts",
@@ -68,16 +70,17 @@
         "./shared/health": "./src/lib/shared/health.ts",
         "./shared/log": "./src/lib/shared/log.ts",
         "./shared/online": "./src/lib/shared/online.ts",
+        "./shared/reachable": "./src/lib/shared/reachable.ts",
         "./shared/page": "./src/lib/shared/page.ts",
         "./shared/trace": "./src/lib/shared/trace.ts",
         "./shared/url": "./src/lib/shared/url.ts",
         "./shared/createSubscriber": "./src/lib/shared/createSubscriber.ts",
         "./ui/html": "./src/lib/ui/html.ts",
+        "./ui/state": "./src/lib/ui/state.ts",
         "./ui/effect": "./src/lib/ui/effect.ts",
-        "./ui/scope": "./src/lib/ui/scope.ts",
-        "./ui/deferResume": "./src/lib/ui/deferResume.ts",
-        "./ui/enterScope": "./src/lib/ui/enterScope.ts",
-        "./ui/exitScope": "./src/lib/ui/exitScope.ts",
+        "./ui/currentScope": "./src/lib/ui/scope.ts",
+        "./ui/enterRenderScope": "./src/lib/ui/enterScope.ts",
+        "./ui/exitRenderScope": "./src/lib/ui/exitScope.ts",
         "./ui/outbox": "./src/lib/ui/outbox.ts",
         "./ui/dom/mount": "./src/lib/ui/dom/mount.ts",
         "./ui/dom/mountChild": "./src/lib/ui/dom/mountChild.ts",
@@ -100,6 +103,7 @@
         "./ui/dom/attr": "./src/lib/ui/dom/attr.ts",
         "./ui/dom/on": "./src/lib/ui/dom/on.ts",
         "./ui/dom/attach": "./src/lib/ui/dom/attach.ts",
+        "./ui/dom/bindSelectValue": "./src/lib/ui/dom/bindSelectValue.ts",
         "./ui/dom/each": "./src/lib/ui/dom/each.ts",
         "./ui/dom/eachAsync": "./src/lib/ui/dom/eachAsync.ts",
         "./ui/dom/when": "./src/lib/ui/dom/when.ts",