@abide/abide 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # abide
 
+## 0.55.0
+
+### Minor Changes
+
+- b000b40: accept a cache policy on mutating helpers ([`4ddc496`](https://github.com/briancray/abide/commit/4ddc496a1a4c9250f83d6dcbb8711be96f1aeded))
+- dcf9868: Hydration internals consolidated — one pass owner, shared claim verbs, one recovery dance, one child adopter.
+
+    - `runHydrationPass` now owns the hydration pass lifecycle (claim cursor, cache-withhold window, render pass, and the two-phase seed consume) — both entry sites (`hydrate`, the router's hydrating first mount) run the same bracket.
+    - The claim-cursor mechanics live in four verbs (`claimMarker`, `claimRun`, `claimText`, `parkCursor`) instead of ~15 hand-rolled advance sites across the dom helpers; helpers keep their hydrate-vs-create branch and divergence policy.
+    - `discardAndRebuild` carries the shared divergence-recovery dance (remove the SSR boundary, build fresh with the cursor cleared) for the await/try blocks and the child adopter.
+    - **Removed export:** `abide/ui/dom/mountStreamedChild` — `abide/ui/dom/mountChild` is now the single dual-mode child adopter (it probes the markup for inlined vs streamed, so the client build needs no hoistable-child knowledge). Both are compiler-emitted plumbing an author never imports; compiled output now always emits `$$mountChild`.
+    - Congruence decisions once mirrored by hand across the two compiler back-ends are now single shared sites: the branch render-path segment alphabet (`BRANCH_SEGMENT`), the `{#await}` bare-cell subject classification (`awaitSubjectExpr`), and `<Child/>` render-path ordinals (`componentOrdinals`, one document-order walk — fixing a latent SSR↔client ordinal desync for a `{:default}` case that isn't last and for components in slot content).
+    - Warm-seed adoption is two-phase (ADR-0048 first slice): a hydration pass marks the `CELL_SEED`/`DOC_SEED` entries it adopts and deletes them only on a clean exit, so a desync throw hands the seeds to the cold rebuild directly — the `warmSeedBackup`/`restoreWarmSeeds` shadow-copy recovery is deleted.
+
+    Server markup and authored APIs are untouched (the `__abideSeeds` wire-global change ships separately).
+
+- f1e925e: `await` now blocks a **script** read the same way it blocks a template read — pending propagates through the whole dependency graph (ADR-0046).
+
+    Previously only _template_ reads of an `await`-marked `computed`/`linked` cell suspended; a _script_ read (a `computed`/derive seed like `computed(() => result.root)` over a blocking `result`) peeked `undefined` while pending, so on a cold client navigation a downstream script derivation dereferenced `undefined` and crashed. Now a read of a pending blocking cell suspends its reader wherever it happens: a derive over it withholds and re-runs on settle, an async seed that reads a pending blocking dependency stays pending (not error), and the SSR barrier drains to a fixpoint so chained blocking cells resolve in order and bake correct values into the first-pass HTML.
+
+    Whether a read pauses is now a property of the **cell** (its `blocking`/`await` bit — the same one that decides SSR-barrier registration), not of the read site: there is one read callee, `$$readCell`, script and template, client and server. The separate `$$readCellBlocking` codegen path and the `abide/ui/dom/readCellBlocking` export are removed; bare/streaming reads (no `await`) are unchanged.
+
+    **Breaking:** a script read of an `await` cell now suspends where it previously returned `undefined` while pending. Read a blocking cell inside a `computed`/derive or the template — a plain top-level `const x = cell.field` cannot pause (it is not a graph node) and is fatal at mount, exactly as `undefined.field` already was.
+
+### Patch Changes
+
+- b000b40: runHydrationPass owns the hydration pass lifecycle ([`0ede531`](https://github.com/briancray/abide/commit/0ede531971e6c351397c2c8c4eea248c37bdd399))
+- b000b40: abide check reads a bare async {#for} source as its resolved peek ([`10b78cf`](https://github.com/briancray/abide/commit/10b78cfe46ef5c6719087ed29f6238ed0d91f348))
+- b000b40: code-review fixes across the reactive core, hydration seeds, and {#await} ([`1d91f49`](https://github.com/briancray/abide/commit/1d91f491bc16f3120f1e513a0db0a6e2e225c77f))
+- b000b40: anchoredBranch owns anchor parking; await/try use advanceClaim ([`473f289`](https://github.com/briancray/abide/commit/473f2894ae02bcbcd67c4ca5d6b45b7de9b1439c))
+- b000b40: name the hydration-cursor advance (advanceClaim) ([`50a2d3d`](https://github.com/briancray/abide/commit/50a2d3d69cfbd82effb2980ba53e58011928dc47))
+- b000b40: consolidate simplify cleanups across shared/ui ([`5956928`](https://github.com/briancray/abide/commit/595692861152619c95a8a7eb83f48fd6d016ec37))
+- b000b40: two-phase warm-seed consume replaces the shadow-copy recovery ([`5b07997`](https://github.com/briancray/abide/commit/5b07997bb7cd01112161f5e67f698e438a96ce1b))
+- b000b40: one degradation site for every hydration seed ([`5bb7fd4`](https://github.com/briancray/abide/commit/5bb7fd490ba2b401cf5c88d616b5ba6c1e420aa5))
+- b000b40: branch segments, await subjects, and child ordinals decided once ([`6f2981d`](https://github.com/briancray/abide/commit/6f2981d5ac49c14b693228c41c14dc54e92a3367))
+- b000b40: appendTextAt's create path delegates to appendText ([`a178acd`](https://github.com/briancray/abide/commit/a178acd4a2dc21477b722a95da99c63d77b794bd))
+- b000b40: hydration claim verbs own the cursor mechanics ([`a624939`](https://github.com/briancray/abide/commit/a624939eb2ff625e4a52c06bf324c45b02ec6d51))
+- b000b40: auto-wrap nested-<script> state.computed/linked bare seeds ([`c4aa0eb`](https://github.com/briancray/abide/commit/c4aa0ebb686875236ba945c15de88278098b10b8))
+- b000b40: mountStreamedChild delegates every mount to mountChild ([`d794580`](https://github.com/briancray/abide/commit/d794580572610304019b698340b5477b7a326241))
+- b000b40: regenerate AGENTS.md + README for amend and cache-on-mutating surface ([`ddef71c`](https://github.com/briancray/abide/commit/ddef71c8ffceab01dcea2a2e49397df29795be2e))
+- 856901e: `{#await <cell>}` now awaits an async cell's resolution instead of peeking its `undefined`-while-pending value (ADR-0047).
+
+    `{#await rates}` where `const rates = state.computed(getRates(...))` used to lower its subject to `$$readCell(rates)` — a peek — so a pending cell read `undefined`, fired `{:then}` immediately, and `{:then data}` crashed dereferencing `data.foo` on `undefined`. (`{#if}`/`{#switch}` cell subjects already avoided this with a `cellPending` guard; `{#await}` never got the equivalent, so it regressed the day a `computed`/`linked` of an async source became a peek-cell.) A bare cell subject is now passed raw and normalised by `$$awaitSubject`, which resolves an async cell to a promise-of-its-value (showing the pending branch until it settles, then `{:then}`, or `{:catch}` on error — SWR on a refresh) and unwraps a lazy `computed(promise)` to its held promise. `{#await getFoo()}` (a plain promise) is byte-identical, on the client, on hydrate, and in the SSR stream.
+
+- d33ed87: `computed`/`linked` now honor the bare-seed contract (ADR-0045) when a bare seed reaches the runtime literally — a branch-nested `<script>` (`{:then names}` + `let total = state.computed(names.length)`) or a direct JS caller. The compile-time `wrapSeed` normalization only covers a component's leading script; a nested branch script keeps its calls literal, so the raw value hit the primitive: `computed(3)` stored `3` as the node's compute and the first read crashed (`node.compute is not a function`), killing the SSR stream mid-drain — a blank page after the shell. Both primitives now route a non-function seed by value: a promise → a streaming async cell, a stream → a frame cell, any other value → a constant seed. Regression-tested against the kitchen-sink templating/async live demo shape.
+- f4e98bd: A bare rpc read (`fn(args)`) no longer derives its cache key twice. The callable already computes `keyForRemoteCall(method, url, args)` to tag its rpc-error registry entries, then `readThrough` re-derived the identical string (`callable.raw` carries the same method/url) on every read — a query-string encode for GET/DELETE or a canonical-JSON stringify for body methods, warm cache hits included. The callable now threads its key into `cache.read` and `readThrough` reuses it; the public `cache()` and raw paths still derive their own. Behavior is unchanged — the two keys were provably identical — this just removes the duplicate work from the framework's primary read path.
+- e8f2144: `invalidate(fn, args)`, `refresh(fn, args)`, and `amend(fn, args)` now resolve their target entry with a direct store lookup instead of scanning every cache entry in every store. A `fn + args` selector identifies exactly one key, so the full-store scan it previously ran was O(total cache entries) work to act on a single known key — noticeable for `amend`, which the real-time path can fire once per incoming socket frame. Behavior is unchanged (the scan is still used for bare-fn, tag, and wire-driven selectors that can match many entries); this is purely a hot-path optimization.
+- 171fdee: One hydration seed manifest: the four passive warm-seed globals (`__abideResume`, `__abideCells`, `__abideDocs`, `__abideSockets`) collapse into one kind-partitioned `window.__abideSeeds` (ADR-0048). The in-bundle names (`RESUME`, `CELL_SEED`, `DOC_SEED`, `SOCKET_SEED`) stay as views onto its partitions, so consumers are unchanged; the inline SSR swap/seed scripts write the `resume` partition. Each partition self-initializes, so the vanilla scripts and the bundle compose in either run order. The live streamed-cell machinery and the head collector buffer stay separate — they are apply-timing phases (ADR-0040), not passive manifests. Internal wire-shape change only; `__SSR__` and all authored APIs are untouched.
+
 ## 0.54.0
 
 ### Minor Changes

package/README.md

@@ -1,65 +1,75 @@
 # abide
 
-**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.**
+**One typed declaration fans out to HTTP, a browser proxy, a CLI, an MCP tool, and an OpenAPI spec — in a single Bun runtime, for humans and machines alike.**
 
-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.
+abide is an isomorphic framework where a server RPC is one typed function: the bundler swaps its runtime per side (in-process on the server, `fetch` in the browser) and projects the same declaration onto every other surface. The `.abide` component grammar ties those RPCs, live sockets, and reactive state into one page that server-renders and hydrates.
 
-- One direct dependency (TypeScript), one runtime (Bun ≥ 1.3.0).
+- One direct dependency (TypeScript); one runtime (Bun ≥ 1.3). Tailwind is an optional peer.
 
 ## Quick start
 
 ```sh
-bunx abide scaffold my-app   # scaffold, install, and start the dev server
+bunx abide scaffold my-app   # scaffolds the project, installs deps, starts the dev server
 ```
 
+Or run the kitchen-sink example:
+
 ```sh
-# or explore the full feature tour
 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 dev
 ```
 
 ## RPCs
 
-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.
+An RPC is one export per file under `src/server/rpc/` — the file path is the URL. The handler's typed input parameter is the contract: at build it projects to JSON Schema (ADR-0030) that drives the MCP tool, CLI flags, and OpenAPI operation. A Standard Schema (zod / valibot / arktype, unadapted) in `schemas.input` adds runtime validation on top.
 
 ```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 { recentMessages } from '../db.ts'
+import { listMessages } 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 } },
+  async ({ limit }: { limit: number }) => json(await listMessages(limit)),
+  { schemas: { input: z.object({ limit: z.number().max(100) }) } },
 )
 ```
 
-One declaration branches to every surface:
+One declaration, five surfaces:
 
 ```text
-        export const getMessages = GET(handler, { schemas })
+                        getMessages  (src/server/rpc/getMessages.ts)
                               │
-   ┌──────────┬──────────────┼──────────────┬──────────────┐
-   ▼          ▼              ▼              ▼              ▼
- 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
+   ┌──────────────┬──────────┼───────────────┬───────────────────┐
+   ▼              ▼          ▼               ▼                   ▼
+ SSR call     browser      MCP tool        CLI               OpenAPI op
+ (in-proc)    fetch        get_messages    app get-messages   GET /rpc/
+ smart read   typed proxy  (read → auto)   --limit 20         getMessages
 ```
 
-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 }`.
+A **typed input** unlocks the CLI, and for a read-only method (GET/HEAD) the MCP tool, with no hand-written schema — the projected shape is the machine-advertisable contract. A mutating method (POST/PUT/PATCH/DELETE) never auto-exposes to MCP; it needs explicit `clients: { mcp: true }`.
+
+```ts
+// src/server/rpc/sendMessage.ts — a plainly-typed mutation, opted into MCP
+import { POST } from '@abide/abide/server/POST'
+import { json } from '@abide/abide/server/json'
+import { appendMessage } from '../db.ts'
+
+export const sendMessage = POST(
+  async ({ text }: { text: string }) => json(await appendMessage(text)),
+  { clients: { mcp: true } },
+)
+```
 
-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()` / `.amend(...)` / `.peek()` / `.pending()` / `.refreshing()` / `.error()`, and — when the handler streams (`jsonl`/`sse`) — a bare call that returns an `AsyncIterable`.
+Consume it many ways. The **bare call `fn(args)` is the smart read** — cached, coalesced, reactive, isomorphic (in-process during SSR, `fetch` in the browser). Alongside it: `fn.raw(args, init?)` for the raw `Response`, and the probes/mutators `fn.pending()` / `fn.refreshing()` / `fn.error()` / `fn.peek()` / `fn.refresh()` / `fn.invalidate()` / `fn.amend(...)`. A streaming handler (`jsonl`/`sse`) makes the bare call return a `Subscribable`. There is no `cache()` wrapper — the bare call carries the caching.
 
-> 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`.
+> Query / path / form args auto-coerce from the endpoint's typed shape (ADR-0028): a numeric / boolean / date field arrives already typed, so no `z.coerce` is needed — 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 `ABIDE_CLIENT_TIMEOUT`.
 
 ## 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`.
+A socket is one broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>`; every socket multiplexes onto one WebSocket at `/__abide/sockets`.
 
 ```ts
 // src/server/sockets/chat.ts
@@ -67,163 +77,173 @@ import { socket } from '@abide/abide/server/socket'
 import { z } from 'zod'
 
 export const chat = socket({
-    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
+  schema: z.object({ id: 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
 })
 ```
 
-`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.
+The HTTP face is `/__abide/sockets/<name>`: `GET` returns the retained tail, `POST` publishes (gated by `clientPublish`).
 
 ## Components
 
-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:
+A `.abide` component is a single page that server-renders and hydrates. This one imports the RPC and socket above and exercises the whole grammar.
 
 ```html
 <script>
-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 { getMessages } from '$server/rpc/getMessages.ts'
+import { sendMessage } from '$server/rpc/sendMessage.ts'
+import { chat } from '$server/sockets/chat.ts'
 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' } = props()
+const { room = 'general' } = props()
 
-let limit = state(20)                          // writable cell, read/reassigned as a plain variable
 let draft = state('')
-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 limit = state(20)
+let live = state(true)
+let tab = state('feed')
+let unread = state(0)
 
-const rootAttrs = { role: 'log' }
-const extra = { compact: true }
-const get = () => draft.toUpperCase()
-const set = (next: string) => { draft = next }
+// state.computed — read-only derived; state.linked — writable, reseeded from a thunk
+let trimmed = state.computed(() => draft.trim())
+let title = state.linked(() => `#${room}`)
 
-// 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 — the single reaction primitive (client-only): a cell, then a socket
+watch(trimmed, next => console.debug('draft', next))
+watch(chat, frame => { unread += 1 })
 
-function focus(node: HTMLElement) { node.focus() }
-function connection() { return chat.pending() ? 'connecting' : 'open' }
-function risky() { return draft.at(999)!.length }
+const badge = html`<sup>${unread}</sup>`
 
 async function send() {
-    await sendMessage({ text: trimmed })       // a mutating RPC from an event handler
-    draft = ''
+  if (!trimmed) return
+  await sendMessage({ text: draft })   // mutating RPC in an event handler
+  draft = ''
 }
+
+// an attach directive: run against the element, return a teardown
+function autofocus(node: HTMLElement) {
+  node.focus()
+  return () => {}
+}
+
+// the get/set pair for a derived two-way binding
+function get() { return draft.toUpperCase() }
+function set(next: string) { draft = next }
 </script>
 
-<section class="chat" class:empty={limit === 0} style:--rows={shown} {...rootAttrs}>
-    <h1>{title}</h1>
-
-    <!-- A bare read STREAMS: it peeks `undefined` while pending, so it composes
-         with `??` and the probes. `await` is the marker for the other mode. -->
-    <p class:loading={getMessages.pending({ limit })}>
-        {getMessages({ limit })?.length ?? 0} messages
-        {#if getMessages.error({ limit })}<span>failed to load</span>{/if}
-    </p>
-
-    <!-- `{await}` means RESOLVED: the server blocks the flush and the client suspends
-         this region until it settles, so the value is never pending at the read (no `?.`)
-         — the region just shows nothing, then reveals. -->
-    <small>today: {await countToday()}</small>
-
-    <!-- `{#await}` is the explicit opt-in — a distinct pending branch and `{:then}` narrowing. -->
-    {#await getMessages({ limit })}
-        <p>loading…</p>
-    {:then messages}
-        {#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 instanceof Error ? err.message : String(err)}</p>
-    {:finally}
-        <hr />
-    {/await}
-
-    <!-- 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}
-        <p>{risky()}</p>
-    {:catch e}
-        <p>widget crashed: {e instanceof Error ? e.message : String(e)}</p>
-    {:finally}
-        <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>
+<header class="row" class:live={live} style:opacity={live ? 1 : 0.5} {...{ id: 'top' }}>
+  <h1>{title} {badge}</h1>
+  <label><input type="checkbox" bind:checked={live} /> live</label>
+</header>
+
+<!-- bare async read: undefined while pending, composes with ?. and ?? -->
+<p>{getMessages({ limit })?.length ?? 0} loaded</p>
+{#if getMessages.pending()}<span>loading…</span>{/if}
+{#if getMessages.error()}<span role="alert">failed</span>{/if}
+
+<form onsubmit={send}>
+  <input name={room} bind:value={draft} attach={autofocus} />
+  <!-- derived two-way binding: { get, set } -->
+  <input bind:value={{ get, set }} />
+  <button type="submit" disabled={trimmed === ''}>Send</button>
+</form>
+
+<nav>
+  {#for name of ['feed', 'about']}<span>{name}</span>{/for}
+  <label><input type="radio" bind:group={tab} value="feed" /> feed</label>
+  <label><input type="radio" bind:group={tab} value="about" /> about</label>
+</nav>
+
+{#switch tab}
+  {:case 'feed'}
+    <ol>
+      {#for message, i of getMessages({ limit }) ?? [] by message.id}
+        <li style:--i={i}>{message.text}</li>
+      {/for}
+    </ol>
+  {:case 'about'}
+    <p>Room {room}.</p>
+  {:default}
+    <p>—</p>
+{/switch}
+
+<!-- inline await: blocks SSR until the value is in the initial HTML -->
+<p>total: {await getMessages({ limit: 100 })?.length ?? 0}</p>
+
+<!-- {#await} is the opt-in for a distinct pending branch and {:then} narrowing -->
+{#await getMessages({ limit })}
+  <p>loading feed…</p>
+{:then messages}
+  <p>{messages.length} messages</p>
+{:catch failure}
+  <p>{failure instanceof Error ? failure.message : String(failure)}</p>
+{:finally}
+  <hr />
+{/await}
+
+{#if live}
+  <script>
+  // a nested branch <script> — branch-local state, re-seeded per mount, no imports
+  let seen = state(0)
+  let plural = state.computed(() => (seen === 1 ? 'frame' : 'frames'))
+  </script>
+  <style>
+    /* nested <style> scopes to this branch's subtree */
+    p { font-variant-numeric: tabular-nums; }
+  </style>
+  <p>{seen} {plural} this session</p>
+  <ul>
+    {#for await frame of chat}
+      <li>{frame.text}</li>
+    {:catch streamError}
+      <li>{streamError instanceof Error ? streamError.message : String(streamError)}</li>
+    {/for}
+  </ul>
+{:else if unread > 0}
+  <p>{unread} while paused</p>
+{:else}
+  <p>paused</p>
+{/if}
+
+{#try}
+  <Card {...{ tone: 'accent' }} class:wide={live}>
+    <p>{html('<em>trusted</em>')}</p>
+  </Card>
+{:catch renderError}
+  <p>card failed: {renderError instanceof Error ? renderError.message : String(renderError)}</p>
+{:finally}
+  <footer>room {room}</footer>
+{/try}
+
+{#snippet row(message: { id: string; text: string })}
+  <li data-id={message.id}>{message.text}</li>
+{/snippet}
+<ul>{#if getMessages({ limit })}{row({ id: '0', text: 'pinned' })}{/if}</ul>
 
 <style>
-.chat { display: grid; gap: 0.5rem; }
+  /* a root <style> is component-scoped */
+  .row { display: flex; gap: 0.5rem; }
 </style>
 ```
 
-The child component fills the passed content at `{children()}`; `{#if children}…{:else}…{/if}` is the fallback (there is no `<slot>` element, no named slots):
+The child component renders its passed content at `{children()}`, with a fallback:
 
 ```html
 <script>
 import { props } from '@abide/abide/ui/props'
-const { children } = props()
+import type { Snippet } from '@abide/abide/shared/snippet'
+const { tone = 'plain', children } = props<{ tone?: string; children?: Snippet }>()
 </script>
 
-<article class="card">
-    {#if children}{children()}{:else}<p>empty</p>{/if}
-</article>
+<section class:accent={tone === 'accent'}>
+  {#if children}{children()}{:else}<em>empty</em>{/if}
+</section>
 ```
 
+Async reads have no ceremony: the bare call in `{getMessages({ limit })}` is the way — a peek that reads `undefined` while pending and auto-streams on SSR, pairing with `.pending()` / `.error()` for affordances. Reach for `{#await}` only when you want an explicit pending branch, a local `{:catch}`, or `{:then}` narrowing.
+
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.54.0",
+    "version": "0.55.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -86,7 +86,6 @@
         "./ui/exitRenderScope": "./src/lib/ui/exitScope.ts",
         "./ui/dom/mount": "./src/lib/ui/dom/mount.ts",
         "./ui/dom/mountChild": "./src/lib/ui/dom/mountChild.ts",
-        "./ui/dom/mountStreamedChild": "./src/lib/ui/dom/mountStreamedChild.ts",
         "./ui/dom/mergeProps": "./src/lib/ui/dom/mergeProps.ts",
         "./ui/dom/spreadProps": "./src/lib/ui/dom/spreadProps.ts",
         "./ui/dom/restProps": "./src/lib/ui/dom/restProps.ts",
@@ -94,8 +93,8 @@
         "./ui/dom/bindableProp": "./src/lib/ui/dom/bindableProp.ts",
         "./ui/dom/spreadAttrs": "./src/lib/ui/dom/spreadAttrs.ts",
         "./ui/dom/readCall": "./src/lib/ui/dom/readCall.ts",
+        "./ui/dom/awaitSubject": "./src/lib/ui/dom/awaitSubject.ts",
         "./ui/dom/readCell": "./src/lib/ui/dom/readCell.ts",
-        "./ui/dom/readCellBlocking": "./src/lib/ui/dom/readCellBlocking.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",

package/src/lib/server/rpc/defineRpc.ts

@@ -94,7 +94,8 @@ export function defineRpc<Args, Return>(
            alongside the 200. Absent on the fail-open path — the surface then omits the error
            responses exactly as before. */
         errorJsonSchemas?: ErrorJsonSchemas
-        /* Endpoint cache policy (ADR-0020) — read helpers only; readThrough's bottom layer. */
+        /* Endpoint cache policy (ADR-0020) — any method (a mutating rpc may cache too);
+           readThrough's bottom layer. */
         cache?: CachePolicy<Args>
         /* Endpoint stream policy (ADR-0020) — streaming read helpers only; replay depth `n`. */
         stream?: StreamPolicy

package/src/lib/server/rpc/types/RpcHelper.ts

@@ -74,30 +74,33 @@ type RpcSchemas = {
 
 /*
 Options every rpc overload accepts: the `schemas` namespace, the `clients` surface
-flags (browser/mcp/cli), the same-origin
-CSRF exemption (`crossOrigin`), the pre-parse body-byte ceiling
-(`maxBodySize`), and the per-surface handler `timeout` (ms). Read helpers add the
-endpoint `cache`/`stream` policy (ADR-0020); mutating helpers add neither — a write has
-no replayable value to retain or stream. The kind-scoping is what makes `POST(fn, { cache })`
-a compile error rather than a silent no-op. The single canonical source both `defineRpc`
-and `RpcRegistryEntry` project from.
+flags (browser/mcp/cli), the same-origin CSRF exemption (`crossOrigin`), the pre-parse
+body-byte ceiling (`maxBodySize`), the per-surface handler `timeout` (ms), and the
+endpoint `cache` policy (ADR-0020). `cache` is shared by both kinds: a mutating rpc
+whose method is a transport choice (a POST that carries a large `code` payload in its
+body yet is a pure function of its args) still coalesces/memoises like a read — the
+runtime already routes `fn.cache` through `readThrough` regardless of method. What stays
+read-only is `stream` (`RpcReadOpts`) — a write has no replayable value to stream.
+Generic over `Args` so `cache.tags`'s `(args) => string[]` form is typed against the
+rpc's own argument shape. The single canonical source both `defineRpc` and
+`RpcRegistryEntry` project from.
 */
-type RpcSharedOpts = {
+type RpcSharedOpts<Args> = {
     schemas?: RpcSchemas
     clients?: Partial<ClientFlags>
     crossOrigin?: boolean
     maxBodySize?: number
     timeout?: number
+    cache?: CachePolicy<Args>
 }
 
 /*
-Read-helper (GET/HEAD) options: the shared base plus the endpoint `cache` policy
-(`ttl`/`tags`/`throttle`/`debounce`/`shared`) and `stream` policy (`n`, replay depth).
-Generic over `Args` so `cache.tags`'s `(args) => string[]` form is typed against the
-rpc's own argument shape.
+Read-helper (GET/HEAD) options: the shared base (including `cache`) plus the endpoint
+`stream` policy (`n`, replay depth) — the one option kind-scoped to replayable reads,
+since a write has no replayable stream. Generic over `Args`, threaded into the shared
+base so `cache.tags`'s `(args) => string[]` form is typed against the rpc's own args.
 */
-type RpcReadOpts<Args> = RpcSharedOpts & {
-    cache?: CachePolicy<Args>
+type RpcReadOpts<Args> = RpcSharedOpts<Args> & {
     stream?: StreamPolicy
 }
 
@@ -147,11 +150,15 @@ export type RpcHelper = {
 }
 
 /*
-The mutating helpers (POST/PUT/PATCH/DELETE). The base opts is the shared `RpcSharedOpts`
-(no `cache`/`stream`) — coalesce-only is the method default and a write has no replayable
-value to retain or stream — which is what makes `cache`/`stream` a compile error here while
-they stay legal on the read helpers (`RpcReadOpts`) — the kind-scoping. Overloads mirror the read helpers by argument source
-(multipart-upload, schema'd, schemaless-with-opts, bare).
+The mutating helpers (POST/PUT/PATCH/DELETE). The base opts is the shared `RpcSharedOpts`,
+which carries `cache` — a mutating rpc still accepts a cache policy (a POST that is a pure
+function of its args, using the body only to carry a large payload, coalesces/memoises like
+a read; the runtime honours `fn.cache` regardless of method). Note the method default for a
+write stays coalesce-only: a no-ttl write is dropped on settle (the mutation idiom), so
+retention across the in-flight window needs an explicit `cache.ttl` (or `shared`). Only
+`stream` stays read-only (`RpcReadOpts`) — a write has no replayable stream — so `POST(fn,
+{ stream })` remains a compile error while `POST(fn, { cache })` is legal. Overloads mirror
+the read helpers by argument source (multipart-upload, schema'd, schemaless-with-opts, bare).
 */
 export type MutatingRpcHelper = {
     <
@@ -163,16 +170,16 @@ export type MutatingRpcHelper = {
             args: StandardSchemaV1.InferOutput<InputSchema> &
                 StandardSchemaV1.InferOutput<FilesSchema>,
         ) => R | Promise<R>,
-        opts: RpcSharedOpts & {
+        opts: RpcSharedOpts<StandardSchemaV1.InferInput<InputSchema>> & {
             schemas: { input: InputSchema; files: FilesSchema; output?: StandardSchemaV1 }
         },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
     <R extends Response, InputSchema extends StandardSchemaV1 = StandardSchemaV1>(
         fn: (args: StandardSchemaV1.InferOutput<InputSchema>) => R | Promise<R>,
-        opts: RpcSharedOpts & {
+        opts: RpcSharedOpts<StandardSchemaV1.InferInput<InputSchema>> & {
             schemas: { input: InputSchema; output?: StandardSchemaV1 }
         },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
-    <F extends RpcFn>(fn: F, opts: RpcSharedOpts): RpcOf<F>
+    <F extends RpcFn>(fn: F, opts: RpcSharedOpts<RpcArgs<F>>): RpcOf<F>
     <F extends RpcFn>(fn: F): RpcOf<F>
 }