@abide/abide 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # abide
 
+## 0.52.0
+
+### Minor Changes
+
+- 83f4e5e: warn on the inert watch(cell.member) source ([`554d3ff`](https://github.com/briancray/abide/commit/554d3ffbdef39a40ccb77c58017b759dbdcb17c2))
+- e0c200b: `abide check` now type-checks the project's `.ts` files too, not only `.abide` templates. The `.ts` files were already loaded into the shadow program to resolve component imports, but their own diagnostics were never reported — so a mistyped `navigate('/p/[id]', {})`, `url()`, or `fn.patch()` call (or any type error) in an rpc handler, `app.ts`, or a `$shared` helper passed `abide check` silently. It now surfaces there, making `abide check` a complete type-check (templates + `.ts`) rather than templates only. Scoped to the project's own root files — a dependency or monorepo sibling resolved on demand is not reported. No new public API.
+- 0858cd6: add `/completions <bash|zsh|fish>` to the generated CLI binary — prints a shell completion script that tab-completes command names and their `--flags` (with `--no-<flag>` for booleans). Candidates derive from the baked manifest via a live `/completions --query` callback, so completion always reflects the binary's real surface and can't drift from dispatch. No new public export.
+- f42c33c: Add a path-addressed hydration-divergence signal on the DEBUG-gated `hydrate` channel (`DEBUG=hydrate`, or `localStorage['abide-debug'] = 'hydrate'` in the browser). With the channel off, behavior is unchanged — a claim divergence still throws the hard guard and the router recovers cold. With it on: a **text** divergence warns with the render-path of the enclosing component/branch/row and keeps hydrating, so one reload surfaces every mismatch instead of aborting at the first; a **structural** divergence names its path before throwing; and an **attribute** divergence — previously invisible, since binding always overwrote the server value — now warns too. The render-path is coarse (it locates the component, the detail names the value) and the compiled class/style/prop setters aren't covered yet. No new public API.
+- fca2f95: add `abide/shared/invalidate` and broadcast both staleness verbs across clients (ADR-0041).
+
+    `invalidate(selector?, args?)` is reintroduced as the distinct DROP verb (next read reloads lazily; a mounted retained reader revalidates stale-in-place), paired with the existing `refresh` REFETCH verb. Instance sugar `fn.invalidate(args?)` sits beside `fn.refresh(args?)`.
+
+    Both verbs are now isomorphic: applied locally on the client, and on the SERVER they broadcast to every connected client over a reserved, server-publish-only `__abide/cache` socket (live-only, no replay — an offline client falls back to SWR staleness). **`refresh`'s server behaviour changed** from a local throwaway refetch that reached zero browsers to a cross-client broadcast — a semantic change to an existing public verb. Producer/closure and bare match-all selectors are not cross-client serializable and are rejected when broadcast from the server. The `__abide/*` socket namespace is now reserved (a user socket file may not declare it).
+
+- 1c1d115: add `abide/server/render` — `render(path, params?, query?)` renders a page route to its HTML string in-process, through the same pipeline (app.html shell, layout chain, params, inline rpc reads) an HTTP GET of that URL runs, so a page stays directly linkable and its emailed form is one call away. Arg shape mirrors `url()`/`navigate`.
+- ee96a2e: Plain `state(initial)` now warm-seeds from the server across hydration, so a nondeterministic initializer carries the server's value through instead of recomputing a divergent one on the client. `state(crypto.randomUUID())`, `state(Date.now())`, `state(Math.random())` — previously the client re-ran the initializer on hydrate and produced a different value than the SSR HTML (a divergence class the `hydrate` channel now reports). Each rendered scope's document snapshot is serialized into `__SSR__.docs` keyed by its render-path id (the same keying the async-cell warm-seed uses), and on hydration the first write to each slot adopts the server value (consume-once) while the throwaway fresh init is discarded. No new public API — same `state()` call, same authoring. Values that don't round-trip the wire codec (functions, class instances) or state read only client-side fall back to a cold init, unchanged.
+
+### Patch Changes
+
+- 83f4e5e: generate .d.ts augmentations before type-checking .ts files ([`5da85e2`](https://github.com/briancray/abide/commit/5da85e2a2f411c221bb552b60b187ebee836d3ba))
+- 83f4e5e: forward a 0-based completion index from the zsh wrapper ([`6d14ccd`](https://github.com/briancray/abide/commit/6d14ccd3aaa8467948fe78dbc4462b40c6ea6750))
+- 83f4e5e: dedupe mirrored maps, skip the inert reaction pass ([`b938e10`](https://github.com/briancray/abide/commit/b938e1058b10d0fa7881d9cd4e3f774bb1dc35c2))
+- 83f4e5e: reflect .ts checking, the hydrate channel, and state seeding ([`e97f0e0`](https://github.com/briancray/abide/commit/e97f0e0c3b4c5bafde99335663cb88d476ff64cc))
+- 83f4e5e: make the bare seed the idiomatic computed/linked form ([`f889416`](https://github.com/briancray/abide/commit/f889416eedab23346c870d491c75b7e0f361bd8e))
+- 83f4e5e: document invalidate, server-side broadcast, and CLI completions ([`fccc4b4`](https://github.com/briancray/abide/commit/fccc4b4e833ea49871c1a955743ce807d1902a28))
+- 090d28e: `abide check` (and the editor shadow) now type-check a `computed`/`linked` seed written with a top-level `await` — `state.computed(await load())` — as its resolved value, instead of flagging a spurious "top-level await" error and mis-typing the binding (which forced `as unknown as Awaited<…>` casts downstream). The shadow now mirrors the compiler's `wrapSeed` lowering: a non-thunk seed is normalised to a thunk (async when it carries a top-level await) and read through a helper that unwraps a promise/stream to the value a bare cell read peeks. A bare `state(await …)` — not a `computed`/`linked` seed — is still correctly flagged, since it genuinely breaks the synchronous build.
+- 129b404: Writing to a `linked` cell from a component `<script>` now works — `let draft = state.linked(() => source); draft = draft + 1` (and `+=`, `++`, `--`, `??=`). Previously the compiler lowered every `linked` reference through `$$readCell(name)` (a call), so an assignment target became `$$readCell(draft) = …` and the build failed with "Invalid assignment target" — only `bind:value={draft}` could write a linked cell, despite `linked` being documented as writable. Assignments to a `linked` binding now lower through a new `$$writeCell` helper (`abide/ui/dom/writeCell`) that dispatches `.value =` for a sync `State` seed and `.set(...)` for an async/stream `AsyncState` seed.
+- 9154f36: The client build of an `$rpc` module now emits a minimal module — the `remoteProxy` fetch plus only the top-level statements the endpoint `opts` transitively reaches — instead of keeping the whole handler file and trusting tree-shaking to drop the server bits. Previously, server code reachable from module-level handler support (the common `const db = getDb()` shape, where `getDb` imports `bun:sqlite`) survived handler-elision and was _loaded_ on the browser target, failing the build with a raw `Browser build cannot import Bun builtin: "bun:sqlite"` before abide's own reachability guard could give a guided message. Reachability is resolved through the warm rpc `ts.Program` (binder/checker), so an `opts` value built from a module-level const — `schemas: { input: inputSchema }` where `const inputSchema = z.object(...)` — keeps that const and its imports, while anything only the handler touches is never emitted. No public API change; the reachability guard for every other client-reaches-server edge is unchanged, and builds with no warm program fall back to the previous keep-the-file transform.
+
 ## 0.51.0
 
 ### Minor Changes

package/README.md

@@ -1,22 +1,19 @@
 # abide
 
-**One typed declaration, every surface: SSR, browser fetch, MCP, CLI, and OpenAPI from a single Bun runtime.**
+**A type-safe isomorphic framework where one typed declaration is an HTTP endpoint, a CLI subcommand, an MCP tool, and an OpenAPI operation at once.**
 
-abide is an isomorphic HTTP framework where a typed RPC you declare once fans out to an in-process SSR call, a browser fetch, an MCP tool, a CLI subcommand, and an OpenAPI operation — the bundler swaps the runtime per side, so the same callable behaves the same in-process on the server and over `fetch` in the browser. It is built for humans and machines: the same schema that types your code projects the tool, the flag, and the spec.
+You write a handler once; abide fans it out across every surface, and the bundler swaps the runtime per side — the same call reads in-process during SSR and becomes a typed `fetch` in the browser. Built for humans _and_ machines, on a single runtime.
 
 - One direct dependency (TypeScript), one runtime (Bun ≥ 1.3.0).
-- No barrels — every public name is its own module path (`@abide/abide/server/GET`, `@abide/abide/ui/state`, …). The namespace marks the side: `server/*` runs server-side, `ui/*` client-side, `shared/*` isomorphic.
 
 ## Quick start
 
 ```sh
-# Scaffold a project from the bundled template, install it, and start dev.
-bunx abide scaffold my-app
+bunx abide scaffold my-app   # scaffold, install, and start the dev server
 ```
 
-Or clone the kitchen-sink example, which exercises the whole surface:
-
 ```sh
+# or explore the full feature tour
 git clone https://github.com/briancray/abide
 cd abide/examples/kitchen-sink
 bun install
@@ -25,59 +22,44 @@ bun run dev
 
 ## RPCs
 
-An RPC is one export per file under `src/server/rpc/`. The file path is the URL; the declared method helper (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`HEAD`) picks the verb. Attach a `schemas.input` (any Standard Schema — zod, valibot, or arktype, unadapted) and the same schema validates the args and projects the MCP tool, the CLI flags, and the OpenAPI operation.
+An RPC is one export per file under `src/server/rpc/`. The file path is the URL; the handler's typed input drives everything downstream. Any [Standard Schema](https://standardschema.dev) (zod, valibot, arktype — unadapted) validates the arguments and projects the MCP tool, CLI flags, and OpenAPI operation.
 
 ```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 { load } from '$server/db.ts'
-
-export const getMessages = GET((args) => json(load(args.channel, args.limit)), {
-    schemas: {
-        input: z.object({
-            channel: z.string().default('general'),
-            limit: z.number().max(100).default(20),
-        }),
-    },
-})
+import { recentMessages } from '../db.ts'
+
+// The success body's type flows back to every caller; `cache` retains the read.
+export const getMessages = GET(
+    async ({ limit }: { limit: number }) => json(await recentMessages(limit)),
+    { schemas: { input: z.object({ limit: z.number().int().max(100) }) }, cache: { ttl: 5_000 } },
+)
 ```
 
-One declaration, five surfaces:
+One declaration branches to every surface:
 
 ```text
-            export const getMessages = GET(fn, { schemas })
-                               │
-    ┌───────────┬──────────────┼──────────────┬─────────────┐
-    ▼           ▼              ▼              ▼             ▼
- SSR call   browser fetch   MCP tool      CLI subcmd   OpenAPI op
- (bare,     (same call,     (read-only    abide-cli    /openapi.json
-  in-proc)   swap to fetch)  from type)    getMessages
+        export const getMessages = GET(handler, { schemas })
+                              │
+   ┌──────────┬──────────────┼──────────────┬──────────────┐
+   ▼          ▼              ▼              ▼              ▼
+ SSR call   browser        MCP tool       CLI            OpenAPI op
+ the bare   fetch          (read-only,    subcommand     in
+ call,      typed proxy    auto-exposed)  abide cli      /openapi.json
+ in-process fn(args)                      getMessages
 ```
 
-A typed input unlocks the CLI on any RPC, and MCP for read-only methods (`GET`/`HEAD`) — the handler's input type is projected to JSON Schema at build (ADR-0030), so a plainly-typed handler auto-exposes with no hand-written `schemas.input` (declaring one adds runtime validation on top, it isn't what flips the surfaces on). A mutating method never auto-exposes to MCP — it opts in explicitly:
-
-```ts
-// src/server/rpc/sendMessage.ts
-import { POST } from '@abide/abide/server/POST'
-import { json } from '@abide/abide/server/json'
-import { z } from 'zod'
-import { append } from '$server/db.ts'
-
-export const sendMessage = POST((args) => json(append(args.channel, args.body)), {
-    schemas: { input: z.object({ channel: z.string(), body: z.string() }) },
-    clients: { mcp: true }, // a mutating RPC must opt into MCP by hand
-})
-```
+A **typed handler input** is what flips those surfaces on: the input type is projected to JSON Schema at build, so a plainly-typed handler auto-exposes to the CLI and — for read-only methods (`GET`/`HEAD`) — MCP with no hand-written `schemas.input` (a declared `schemas.input` adds runtime validation on top). A mutating method (`POST`/`PUT`/`PATCH`/`DELETE`) never auto-exposes to MCP; opt it in with `clients: { mcp: true }`.
 
-Consume forms are isomorphic. The **bare call `fn(args)` is the smart read** — cached, coalesced, reactive, resolved in-process during SSR and over `fetch` in the browser (there is no `cache()` wrapper; the bare call carries the caching). Alongside it: `fn.raw(args, init?)` for the raw `Response`, and the mutators/probes `fn.refresh()`, `fn.patch(...)`, `fn.peek()`, `fn.pending()`, `fn.refreshing()`, and `fn.error()`. A streaming handler (`jsonl`/`sse`) makes the bare call return a `Subscribable` you iterate.
+Consume it by importing the export. The **bare call `getMessages(args)` is the smart read** — cached, coalesced, reactive, isomorphic (in-process on the server, `fetch` in the browser). Around it sit `getMessages.raw(args, opts?)` for the raw `Response`, the mutators/probes `.refresh()` / `.invalidate()` / `.patch(...)` / `.peek()` / `.pending()` / `.refreshing()` / `.error()`, and — when the handler streams (`jsonl`/`sse`) — a bare call that returns an `AsyncIterable`.
 
-> Query and path args auto-coerce from the endpoint's typed shape — a numeric field arrives as a number, no `z.coerce` needed. The per-RPC `timeout` (a 504 on every surface) is distinct from the client-wide `ABIDE_CLIENT_TIMEOUT`.
+> Query, path, and form args auto-coerce from the endpoint's typed shape at build, so a numeric/boolean/date field arrives already typed — no `z.coerce` (a value that won't parse stays a string, so the schema raises an honest 422). The per-RPC `timeout` (504 on every surface) is distinct from the client transport ceiling `ABIDE_CLIENT_TIMEOUT`.
 
 ## Sockets
 
-A socket is one broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — the same value you `for await` on both sides — and every socket multiplexes onto one WebSocket at `/__abide/sockets`.
+A socket is one broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — iterate it for the live stream — and every socket multiplexes onto one WebSocket at `/__abide/sockets`.
 
 ```ts
 // src/server/sockets/chat.ts
@@ -85,171 +67,160 @@ import { socket } from '@abide/abide/server/socket'
 import { z } from 'zod'
 
 export const chat = socket({
-    schema: z.object({ author: z.string(), body: z.string() }),
-    tail: 20, // retain the last 20 frames for late joiners and reconnects
-    ttl: 60_000, // evict retained frames older than 60s
+    schema: z.object({ user: z.string(), text: z.string() }),
+    tail: 50, // retain the last 50 frames so late joiners / reconnects seed from `.tail()`
+    ttl: 60_000, // evict retained frames older than 60s before replay
 })
 ```
 
-Publish with `chat.publish(frame)`; seed a late reader with `chat.tail(count)`. Each socket also has an HTTP face at `/__abide/sockets/<name>`: `GET` returns the retained tail, and `POST` publishes when `clientPublish` is set.
+`chat.publish(frame)` is isomorphic — server code fans out in-process and to remote subscribers; client code sends a `pub` frame (gated by `clientPublish`, off by default). The HTTP face is `/__abide/sockets/<name>`: a `GET` returns the retained tail, a `POST` publishes.
 
 ## Components
 
-A `.abide` component is HTML with a leading `<script>`. The example below is one page that imports the RPC and socket above and exercises the whole template grammar. Reactive primitives are imported by their own module paths and called bare: `state(0)` is a writable cell you read and reassign as a plain variable (`count`, `count += 1`) — the compiler desugars those to the cell's `.value`; `state.computed(fn)` is read-only derived, `state.linked(fn)` is writable and reseeded from a thunk. `watch(source, handler)` is the single reaction primitive — over a cell, a socket, or an RPC. `props()` is the prop reader, imported from `abide/ui/props`.
-
-Async data has no ceremony: **the bare call in an interpolation — `{getMessages({ limit })}` — is the way to read it.** It's a _peek_ that reads `undefined` while pending (and auto-streams on SSR), so it composes with `?? fallback`, `?.`, `{#if}`, and attributes with no wrapping block; pair it with the `.pending()` / `.error()` probes for loading and error affordances, and use `{await getMessages(...)}` to block SSR until the value is in the initial HTML. The `{#await}…{:then}…{:catch}…{:finally}…{/await}` block is the explicit opt-in — reach for it only when you want a distinct pending branch, a local `{:catch}`, or `{:then}` type-narrowing.
+A `.abide` component is valid HTML with a `<script>`, reactive primitives imported by their own module paths, and mustache control-flow blocks. The page below imports the RPC and socket above and exercises the whole grammar:
 
 ```html
 <script>
-import { getMessages } from '$server/rpc/getMessages.ts'
-import { sendMessage } from '$server/rpc/sendMessage.ts'
-import { chat } from '$server/sockets/chat.ts'
-import MessageCard from '$ui/components/MessageCard.abide'
+import { getMessages } from '$server/rpc/getMessages'
+import { sendMessage } from '$server/rpc/sendMessage'
+import { countToday } from '$server/rpc/countToday'
+import { chat } from '$server/sockets/chat'
+import Card from '$ui/Card.abide'
+import Avatar from '$ui/Avatar.abide'
+import Message from '$ui/Message.abide'
 import { state } from '@abide/abide/ui/state'
 import { watch } from '@abide/abide/ui/watch'
 import { html } from '@abide/abide/ui/html'
 import { props } from '@abide/abide/ui/props'
 
-const { title = 'Chat', ...rest } = props()
-
-type Message = { id: string; author: string; body: string }
+const { title = 'Chat' } = props()
 
-let channel = state('general')
+let limit = state(20)                          // writable cell, read/reassigned as a plain variable
 let draft = state('')
-let pinned = state(false)
-let limit = state(20)
+let notify = state(true)
+let channel = state('general')
+const trimmed = state.computed(() => draft.trim())     // read-only derived
+const shown = state.linked(() => limit)                // writable, reseeded when `limit` changes
 
-let trimmed = state.computed(() => draft.trim())
-let live = state.linked(() => limit)
+const rootAttrs = { role: 'log' }
+const extra = { compact: true }
+const get = () => draft.toUpperCase()
+const set = (next: string) => { draft = next }
 
-const badge = html`<sup class="ml-1 text-xs text-emerald-600">live</sup>`
+// watch — the single reaction primitive: over a cell, then over a live socket.
+watch(limit, (n) => console.log('limit is now', n))
+watch(chat, (frame) => console.log('new message', frame.text))
 
-watch(trimmed, (value) => console.log('draft is now', value))
-watch(chat, (frame) => {
-    live = live + 1
-})
+function focus(node: HTMLElement) { node.focus() }
+function connection() { return chat.pending() ? 'connecting' : 'open' }
+function risky() { return draft.at(999)!.length }
 
-async function submit(event: SubmitEvent) {
-    event.preventDefault()
-    if (trimmed === '') return
-    await sendMessage({ channel, body: trimmed })
+async function send() {
+    await sendMessage({ text: trimmed })       // a mutating RPC from an event handler
     draft = ''
 }
-
-function autofocus(node: HTMLInputElement) {
-    node.focus()
-    return () => {}
-}
-
-const rowProps = { class: 'flex gap-2' }
-
-// Derived two-way binding: read a string, coerce writes back into the numeric cell.
-const get = () => String(limit)
-const set = (next: string) => (limit = Number(next))
 </script>
 
-<section {...rest} class:pinned={pinned} style:opacity={pinned ? '1' : '0.85'}>
-    <h1>{title} {badge}</h1>
-
-    <form onsubmit={submit}>
-        <input bind:value={draft} attach={autofocus} placeholder="Say something" />
-        <label><input type="checkbox" bind:checked={pinned} /> pin</label>
-        <label><input type="radio" bind:group={channel} value="general" /> general</label>
-        <label><input type="radio" bind:group={channel} value="random" /> random</label>
-        <input bind:value={{ get, set }} />
-        <button type="submit">Send</button>
-    </form>
-
-    {#snippet row(message: Message, index: number)}
-        <MessageCard {...rowProps} name={message.author} onclick={() => console.log(index)}>
-            <p>{message.body}</p>
-        </MessageCard>
-    {/snippet}
+<section class="chat" class:empty={limit === 0} style:--rows={shown} {...rootAttrs}>
+    <h1>{title}</h1>
 
-    {#if live > 100}
-        <p>Busy channel</p>
-    {:else if live > 0}
-        <p>{live} updates</p>
-    {:else}
-        <script>
-            let seenAt = state(Date.now())
-            let ageLabel = state.computed(() => `waiting since ${seenAt}`)
-        </script>
-        <style>
-            p { color: gray; }
-        </style>
-        <p>{ageLabel}</p>
-    {/if}
-
-    <!-- The default: a bare peek — `undefined` while pending, composes with `?.`/`??`; probes for affordances. -->
-    <p>
+    <!-- Async reads have no ceremony: the bare call is the way. It peeks
+         `undefined` while pending, so it composes with `??` and the probes. -->
+    <p class:loading={getMessages.pending({ limit })}>
         {getMessages({ limit })?.length ?? 0} messages
-        {#if getMessages.pending({ limit })} · loading…{/if}
-        {#if getMessages.error({ limit })} · failed{/if}
+        {#if getMessages.error({ limit })}<span>failed to load</span>{/if}
     </p>
 
-    <!-- {await fn()} blocks SSR so the value is in the initial HTML (no streamed/pending pass). -->
-    <p>newest: {await getMessages({ limit }).then((list) => list.at(-1)?.author ?? '—')}</p>
+    <!-- `{await}` is an inline read: it blocks SSR until the value is in the HTML. -->
+    <small>today: {await countToday()}</small>
 
-    <!-- The explicit opt-in: a distinct pending branch, a local {:catch}, and {:then} narrowing. -->
+    <!-- `{#await}` is the explicit opt-in — a distinct pending branch and `{:then}` narrowing. -->
     {#await getMessages({ limit })}
-        <p>Loading…</p>
+        <p>loading…</p>
     {:then messages}
-        {#for message, i of messages by message.id}
-            {row(message, i)}
-        {/for}
-    {:catch problem}
-        <p>Failed: {problem.message}</p>
+        {#if messages.length}
+            {#for message, i of messages by message.id}
+                <Message message={message} ondelete={() => sendMessage({ text: '' })} {...extra}>
+                    <Avatar alt={message.user} />
+                </Message>
+            {/for}
+        {:else if limit > 0}
+            <p>no messages yet</p>
+        {:else}
+            <p>raise the limit</p>
+        {/if}
+    {:catch err}
+        <p>{err.message}</p>
     {:finally}
         <hr />
     {/await}
 
-    {#for await frame of chat}
-        <p class="text-sm opacity-70">{frame.author}: {frame.body}</p>
-    {/for}
-
-    {#switch channel}
-        {:case 'general'}
-            <span>General channel</span>
-        {:case 'random'}
-            <span>Random channel</span>
-        {:default}
-            <span>Unknown channel</span>
+    <!-- live socket frames over an AsyncIterable -->
+    <ul>
+        {#for await frame of chat}
+            <li>{frame.user}: {frame.text}</li>
+        {/for}
+    </ul>
+
+    {#switch connection()}
+        {:case 'open'}<span>live</span>
+        {:case 'connecting'}<span>connecting…</span>
+        {:default}<span>offline</span>
     {/switch}
 
     {#try}
-        <MessageCard name="system">
-            <p>System notice</p>
-        </MessageCard>
-    {:catch}
-        <p>Card crashed</p>
+        <p>{risky()}</p>
+    {:catch e}
+        <p>widget crashed: {e.message}</p>
     {:finally}
-        <span class="sr-only">done</span>
+        <span>rendered</span>
     {/try}
+
+    <form onsubmit={send}>
+        <input name="text" bind:value={draft} />
+        <label><input type="checkbox" bind:checked={notify} /> notify</label>
+        <input type="radio" bind:group={channel} value="general" />
+        <input aria-label="shout" bind:value={{ get, set }} />
+        <button attach={focus}>send</button>
+    </form>
+
+    {#snippet stat(label: string, value: number)}
+        <dd>{label}: {value}</dd>
+    {/snippet}
+    <dl>{stat('shown', limit)}</dl>
+
+    <Card>
+        <p>{html`<em>${trimmed}</em>`}</p>
+    </Card>
+
+    {#if limit > 10}
+        <script>
+        // a nested branch script: branch-local state, re-seeded per mount, no imports
+        let expanded = state(false)
+        const label = state.computed(() => (expanded ? 'less' : 'more'))
+        </script>
+        <button onclick={() => (expanded = !expanded)}>{label}</button>
+        <style>
+        button { font-weight: 600; }
+        </style>
+    {/if}
 </section>
 
 <style>
-    section {
-        display: grid;
-        gap: 0.5rem;
-    }
+.chat { display: grid; gap: 0.5rem; }
 </style>
 ```
 
-The capitalised `MessageCard` renders its passed content where it calls `{children()}`. The `<slot>` element was removed — `{children()}` is the single fill point, and `{#if children}{children()}{:else}…{/if}` is the fallback form.
+The child component fills the passed content at `{children()}`; `{#if children}…{:else}…{/if}` is the fallback (there is no `<slot>` element, no named slots):
 
 ```html
 <script>
-    import { props } from '@abide/abide/ui/props'
-    import type { Snippet } from '@abide/abide/shared/snippet'
-    const { name, children, ...rest } = props<{ name: string; children?: Snippet }>()
+import { props } from '@abide/abide/ui/props'
+const { children } = props()
 </script>
 
-<article {...rest}>
-    <strong>{name}</strong>
-    {#if children} {children()} {:else}
-    <em>No content</em>
-    {/if}
+<article class="card">
+    {#if children}{children()}{:else}<p>empty</p>{/if}
 </article>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.51.0",
+    "version": "0.52.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -45,6 +45,7 @@
         "./server/sse": "./src/lib/server/sse.ts",
         "./server/error": "./src/lib/server/error.ts",
         "./server/redirect": "./src/lib/server/redirect.ts",
+        "./server/render": "./src/lib/server/render.ts",
         "./server/request": "./src/lib/server/request.ts",
         "./server/cookies": "./src/lib/server/cookies.ts",
         "./server/env": "./src/lib/server/env.ts",
@@ -58,6 +59,7 @@
         "./server/prompts/definePrompt": "./src/lib/server/prompts/definePrompt.ts",
         "./ui/watch": "./src/lib/ui/watch.ts",
         "./shared/pending": "./src/lib/shared/pending.ts",
+        "./shared/invalidate": "./src/lib/shared/invalidate.ts",
         "./shared/patch": "./src/lib/shared/patch.ts",
         "./shared/peek": "./src/lib/shared/peek.ts",
         "./shared/refresh": "./src/lib/shared/refresh.ts",
@@ -93,6 +95,7 @@
         "./ui/dom/spreadAttrs": "./src/lib/ui/dom/spreadAttrs.ts",
         "./ui/dom/readCall": "./src/lib/ui/dom/readCall.ts",
         "./ui/dom/readCell": "./src/lib/ui/dom/readCell.ts",
+        "./ui/dom/writeCell": "./src/lib/ui/dom/writeCell.ts",
         "./ui/dom/cellPending": "./src/lib/ui/dom/cellPending.ts",
         "./ui/runtime/withPath": "./src/lib/ui/runtime/withPath.ts",
         "./ui/settleAsyncCells": "./src/lib/ui/settleAsyncCells.ts",

package/src/abideResolverPlugin.ts

@@ -396,6 +396,17 @@ export function abideResolverPlugin({
                    program / unresolvable body / no structured field) bakes nothing — a response array
                    stays an array. */
                 const outputWirePlan = rpcServerProgram?.outputWirePlanForModule(args.path)
+                /* The client-only reachability plan: the top-level statements the emitted client
+                   module retains, rooted at the endpoint `opts` (imports + declarations opts
+                   transitively needs). Present → rewriteForClient emits a MINIMAL module so the
+                   handler and its server-only imports are never emitted — nothing server-side loads
+                   or trips the reachability guard (ADR-0022 addendum). Only the client target needs
+                   it; the server rewrite keeps the whole handler. undefined (no warm program /
+                   unresolvable call) falls open to the keep-the-file rewrite. */
+                const clientKeep =
+                    target === 'client'
+                        ? rpcServerProgram?.clientKeepForModule(args.path)
+                        : undefined
                 /* The handler's input args projected to JSON Schema, stamped as `inputJsonSchema` so the
                    runtime OpenAPI parameters/body / MCP inputSchema / inspector input surface renders the
                    real input shape (and the endpoint becomes advertisable) without an author-declared
@@ -410,6 +421,7 @@ export function abideResolverPlugin({
                     outputSchema: returnBodySchema,
                     errorSchemas,
                     outputWirePlan,
+                    clientKeep,
                 })
                 if (!prepared) {
                     throw new Error(

package/src/checkAbide.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
 import ts from 'typescript'
+import { generateDeclarations } from './lib/shared/generateDeclarations.ts'
 import { collectAbideDiagnostics } from './lib/ui/compile/collectAbideDiagnostics.ts'
 import { createShadowProgram, type ShadowProgram } from './lib/ui/compile/createShadowProgram.ts'
 import { interpolationClassifierForRoot } from './lib/ui/compile/interpolationClassifierForRoot.ts'
@@ -15,6 +16,13 @@ the same as each package checked on its own — and the same as the LSP. Returns
 the error count so the CLI can set its exit code.
 */
 export async function checkAbide({ cwd }: { cwd: string }): Promise<number> {
+    /* Materialize the project's generated augmentations (src/.abide/*.d.ts) first: since the
+       check pass now type-checks the project's `.ts` files too (rpc handlers, app.ts, tests),
+       those resolve `app.rpc.<name>` / typed `url('/rpc/…')` off the build-written RpcClient /
+       RpcRoutes augmentations. Without this, a cold `abide check` (CI, fresh clone — `.abide` is
+       gitignored, generated only by dev/build) reports every augmented member as missing. Fails
+       open, so a codegen hiccup degrades to the pre-`.ts`-check behaviour rather than aborting. */
+    await generateDeclarations({ cwd })
     const { diagnostics, checked } = collectByProject(cwd)
     const byFile = new Map<string, AbideDiagnostic[]>()
     for (const diagnostic of diagnostics) {
@@ -64,17 +72,62 @@ function collectByProject(cwd: string): { diagnostics: AbideDiagnostic[]; checke
        WHICH sub-expressions are async must read un-wrapped shadows — so it rides a separate verbatim
        program, built (and reused) here per root. */
     const classifierCache = new Map<string, ShadowProgram | undefined>()
-    const diagnostics = [...byProject].flatMap(([root, paths]) =>
-        collectAbideDiagnostics(
-            createShadowProgram(root, paths, (abidePath) =>
-                interpolationClassifierForRoot(classifierCache, root, abidePath),
-            ),
-        ),
-    )
+    const diagnostics = [...byProject].flatMap(([root, paths]) => {
+        const shadow = createShadowProgram(root, paths, (abidePath) =>
+            interpolationClassifierForRoot(classifierCache, root, abidePath),
+        )
+        /* The shadow program already holds the project's real `.ts` files (loaded so the
+           components' imports/types resolve), but `collectAbideDiagnostics` only reports the
+           `.abide` shadows. Report the `.ts` files too, so a mistyped `navigate`/`url`/`patch`
+           call — or any type error — in an rpc handler, `app.ts`, or a `$shared` helper fails
+           `abide check` instead of only surfacing under a separately-run `tsc`. */
+        return [...collectAbideDiagnostics(shadow), ...collectTsDiagnostics(shadow.program)]
+    })
     const checked = [...byProject.values()].reduce((total, paths) => total + paths.length, 0)
     return { diagnostics, checked }
 }
 
+/* Syntactic + semantic diagnostics for the project's own `.ts` files already in the shadow
+   program. Iterating the ROOT file names (the project's tsconfig inputs) — not every loaded
+   source — scopes this to the project itself: an on-demand-resolved import from node_modules or a
+   monorepo sibling is in the program but never a root, so its errors aren't attributed here.
+   `fileExists` drops the virtual `.abide.ts` shadows and the synthetic asset-modules file (neither
+   is on disk), `isDeclarationFile` drops the default libs and the generated `src/.abide/*.d.ts`,
+   and the `.ts`/`.tsx` guard drops raw `.abide` root entries. Real source coordinates — no remap. */
+function collectTsDiagnostics(program: ts.Program): AbideDiagnostic[] {
+    const diagnostics: AbideDiagnostic[] = []
+    for (const rootName of program.getRootFileNames()) {
+        if (
+            (!rootName.endsWith('.ts') && !rootName.endsWith('.tsx')) ||
+            rootName.includes('/node_modules/') ||
+            !ts.sys.fileExists(rootName)
+        ) {
+            continue
+        }
+        const sourceFile = program.getSourceFile(rootName)
+        if (sourceFile === undefined || sourceFile.isDeclarationFile) {
+            continue
+        }
+        const raw = [
+            ...program.getSyntacticDiagnostics(sourceFile),
+            ...program.getSemanticDiagnostics(sourceFile),
+        ]
+        for (const diagnostic of raw) {
+            if (diagnostic.start === undefined) {
+                continue
+            }
+            diagnostics.push({
+                file: sourceFile.fileName,
+                start: diagnostic.start,
+                length: diagnostic.length ?? 0,
+                message: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+                category: diagnostic.category,
+            })
+        }
+    }
+    return diagnostics
+}
+
 /* Renders one diagnostic as `path:line:col severity message` plus the offending
    line and a caret underline spanning the mapped range. */
 function printDiagnostic(file: string, text: string, diagnostic: AbideDiagnostic): void {

package/src/lib/cli/completeCli.ts

@@ -0,0 +1,38 @@
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Shell-completion candidates for a partially-typed command line, derived
+entirely from the baked manifest so completion can't drift from dispatch.
+`cword` is the token index being completed (the shell's COMP_CWORD /
+CURRENT), `command` is the first positional (`words[1]`). Completing the
+first positional lists every command plus the `/`-prefixed connection
+verbs; past it, the chosen command's flags (mirroring parseArgvForRpc's
+grammar — `--name`, plus `--no-name` for a boolean, and the always-present
+`--json`). The shell filters these by the current prefix.
+*/
+export function completeCli(
+    manifest: CliManifest,
+    cword: number,
+    command: string | undefined,
+): string[] {
+    // Completing the command itself: every rpc/socket command + the connection verbs.
+    if (cword <= 1) {
+        const connection = ['/connect', '/start', '/disconnect', '/help', '/completions']
+        return [...Object.keys(manifest).toSorted(), ...connection]
+    }
+    const entry = command === undefined ? undefined : manifest[command]
+    if (!entry) {
+        return []
+    }
+    const properties =
+        (entry.jsonSchema?.properties as Record<string, { type?: string }> | undefined) ?? {}
+    const flags = ['--json']
+    for (const [key, value] of Object.entries(properties)) {
+        flags.push(`--${key}`)
+        // A boolean flag also accepts its negation, matching printCommandHelp's `--no-<key>`.
+        if (value.type === 'boolean') {
+            flags.push(`--no-${key}`)
+        }
+    }
+    return flags
+}

package/src/lib/cli/printTopLevelHelp.ts

@@ -70,6 +70,7 @@ export function printTopLevelHelp(
     console.log(`  ${programName} /start           start a local instance`)
     console.log(`  ${programName} /disconnect      forget the saved connection`)
     console.log(`  ${programName}                  resume the saved connection (session)`)
+    console.log(`  ${programName} /completions <bash|zsh|fish>   print a shell completion script`)
     console.log(`\n  --help, -h           show this help`)
     console.log(`  <command> --help     show help for a specific command`)
     console.log(`\nenv:`)