@abide/abide 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # abide
 
+## 0.51.0
+
+### Minor Changes
+
+- aec503f: make watch(cell, handler) reactive ([`4db4e3d`](https://github.com/briancray/abide/commit/4db4e3d21cb04dcad5463831621140ec00ccbbe2))
+
+### Patch Changes
+
+- aec503f: correct README/AGENTS and lead the async story with the bare call ([`c96e936`](https://github.com/briancray/abide/commit/c96e93682cc8e05762bcde7bb808850dfdb40b6f))
+
+## 0.50.1
+
+### Patch Changes
+
+- ef143f5: regenerate README + AGENTS surface map ([`8665efa`](https://github.com/briancray/abide/commit/8665efa7eb9f4106882cf246738c08e465d7e8d7))
+
 ## 0.50.0
 
 ### Minor Changes

package/README.md

@@ -1,103 +1,83 @@
 # abide
 
-**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.**
+**One typed declaration, every surface: SSR, browser fetch, MCP, CLI, and OpenAPI from a single Bun runtime.**
 
-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.
+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.
 
-- One direct dependency (TypeScript). One runtime (Bun ≥ 1.3).
+- 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
-bunx abide scaffold my-app   # scaffolds, installs, and starts the dev server
+# Scaffold a project from the bundled template, install it, and start dev.
+bunx abide scaffold my-app
 ```
 
-Or run the kitchen-sink example, which demos the full surface:
+Or clone the kitchen-sink example, which exercises the whole surface:
 
 ```sh
 git clone https://github.com/briancray/abide
-cd abide && bun install
-cd examples/kitchen-sink && bun run dev
+cd abide/examples/kitchen-sink
+bun install
+bun run dev
 ```
 
 ## RPCs
 
-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 `schemas.input`
-(zod, valibot, arktype — no adapter) validates the args and projects the CLI
-flags, the MCP tool, and the OpenAPI operation from the one declaration.
+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.
 
 ```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'
-
-export const getMessages = GET(
-    async ({ room, limit }) => json(await listMessages(room, limit)),
-    {
-        schemas: {
-            input: z.object({
-                room: z.string(),
-                limit: z.coerce.number().default(50),
-            }),
-        },
+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),
+        }),
     },
-)
+})
 ```
 
-That one file fans out:
+One declaration, five surfaces:
 
 ```text
-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
+            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
+```
+
+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 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
-  `NamedAsyncIterable` 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.
+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.
+
+> 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`.
 
 ## Sockets
 
-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`.
+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`.
 
 ```ts
 // src/server/sockets/chat.ts
@@ -105,184 +85,172 @@ import { socket } from '@abide/abide/server/socket'
 import { z } from 'zod'
 
 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)
+    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
 })
 ```
 
-`chat.publish(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`.
+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.
 
 ## Components
 
-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.
+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`.
 
-Nested content becomes the component's `children` prop — an ordinary declared
-prop of type `Snippet` — and renders wherever the component calls
-`{children()}`:
+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.
 
 ```html
 <script>
-    import { props } from '@abide/abide/ui/props'
-    import type { Snippet } from '@abide/abide/shared/snippet'
-
-    const { title, children } = props<{ title: string; children?: Snippet }>()
-</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 { 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'
 
-<section>
-    <h2>{title}</h2>
-    {#if children}{children()}{:else}<p>Nothing here yet.</p>{/if}
-</section>
+const { title = 'Chat', ...rest } = props()
 
-<style>
-    section {
-        border: 1px solid gray;
-    }
-</style>
-```
+type Message = { id: string; author: string; body: string }
 
-And one page tying together the RPC from above, the socket, and the whole
-template grammar:
+let channel = state('general')
+let draft = state('')
+let pinned = state(false)
+let limit = state(20)
 
-```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 { props } from '@abide/abide/ui/props'
-    import Panel from '$ui/components/Panel.abide'
+let trimmed = state.computed(() => draft.trim())
+let live = state.linked(() => limit)
 
-    const { room = 'lobby' } = props<{ room?: string }>()
+const badge = html`<sup class="ml-1 text-xs text-emerald-600">live</sup>`
 
-    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(trimmed, (value) => console.log('draft is now', value))
+watch(chat, (frame) => {
+    live = live + 1
+})
 
-    // watch is the one reaction primitive: a socket, an rpc, or a tracked thunk.
-    watch(chat, () => getMessages.refresh({ room }))
-    watch(() => console.log(author, tone))
+async function submit(event: SubmitEvent) {
+    event.preventDefault()
+    if (trimmed === '') return
+    await sendMessage({ channel, body: trimmed })
+    draft = ''
+}
 
-    // a writable computed lives at the binding: bind:value={{ get, set }}
-    const get = () => draft.trim()
-    const set = (next) => (draft = next)
+function autofocus(node: HTMLInputElement) {
+    node.focus()
+    return () => {}
+}
 
-    const focus = (element) => element.focus()
-    const panelProps = { title: 'Live feed' }
-    const draftAttrs = { placeholder: 'say something', autocomplete: 'off' }
+const rowProps = { class: 'flex gap-2' }
 
-    async function send() {
-        await sendMessage({ room: roomDraft, author, text: draft })
-        draft = ''
-    }
+// 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>
 
-{#snippet line(message)}
-    <li>{message.author}: {message.text}</li>
-{/snippet}
-
-<Panel {...panelProps}>
-    <h1 class:muted={!notify} style:opacity={notify ? '1' : '0.6'}>
-        {room} — {shout}
-    </h1>
+<section {...rest} class:pinned={pinned} style:opacity={pinned ? '1' : '0.85'}>
+    <h1>{title} {badge}</h1>
 
-    <!-- {await expr} awaits inline (blocking); a Promise-typed {expr} would stream -->
-    <p>total messages: {await getMessages({ room }).then((all) => all.length)}</p>
+    <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>
 
-    {#await getMessages({ room })}
-        <p>loading…</p>
+    {#snippet row(message: Message, index: number)}
+        <MessageCard {...rowProps} name={message.author} onclick={() => console.log(index)}>
+            <p>{message.body}</p>
+        </MessageCard>
+    {/snippet}
+
+    {#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>
+        {getMessages({ limit })?.length ?? 0} messages
+        {#if getMessages.pending({ limit })} · loading…{/if}
+        {#if getMessages.error({ limit })} · failed{/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>
+
+    <!-- The explicit opt-in: a distinct pending branch, a local {:catch}, and {:then} narrowing. -->
+    {#await getMessages({ limit })}
+        <p>Loading…</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}
-            <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>
+        {#for message, i of messages by message.id}
+            {row(message, i)}
+        {/for}
+    {:catch problem}
+        <p>Failed: {problem.message}</p>
     {:finally}
-        <p>checked just now</p>
+        <hr />
     {/await}
 
-    <ol>
-        {#for await message of chat}
-            {line(message)}
-        {/for}
-    </ol>
+    {#for await frame of chat}
+        <p class="text-sm opacity-70">{frame.author}: {frame.body}</p>
+    {/for}
 
-    {#switch tone}
-        {:case 'friendly'}
-            <p>{html`<em>be&nbsp;kind</em>`}</p>
+    {#switch channel}
+        {:case 'general'}
+            <span>General channel</span>
+        {:case 'random'}
+            <span>Random channel</span>
         {:default}
-            <p>say anything</p>
+            <span>Unknown channel</span>
     {/switch}
 
     {#try}
-        <p>{JSON.parse(draft).summary}</p>
+        <MessageCard name="system">
+            <p>System notice</p>
+        </MessageCard>
     {:catch}
-        <p>draft isn't JSON yet</p>
+        <p>Card crashed</p>
+    {:finally}
+        <span class="sr-only">done</span>
     {/try}
-
-    <form onsubmit={(event) => { event.preventDefault(); send() }}>
-        <input attach={focus} bind:value={draft} {...draftAttrs} />
-        <input bind:value={{ get, set }} />
-        <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>
-</Panel>
+</section>
 
 <style>
-    form {
-        display: flex;
+    section {
+        display: grid;
         gap: 0.5rem;
     }
-    .muted {
-        color: gray;
-    }
 </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.
+
+```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 }>()
+</script>
+
+<article {...rest}>
+    <strong>{name}</strong>
+    {#if children} {children()} {:else}
+    <em>No content</em>
+    {/if}
+</article>
+```
+
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.50.0",
+    "version": "0.51.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

package/src/lib/ui/compile/compileShadow.ts

@@ -39,9 +39,6 @@ function shadowPreamble(importedReactives: ReadonlySet<string>): string {
         importedReactives.has('effect')
             ? undefined
             : `import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'`,
-        importedReactives.has('watch')
-            ? undefined
-            : `import { watch } from '${ABIDE_PACKAGE_NAME}/ui/watch'`,
         `import { snippet } from '${ABIDE_PACKAGE_NAME}/shared/snippet'`,
         `import { scope } from '${ABIDE_PACKAGE_NAME}/ui/currentScope'`,
         importedReactives.has('state')
@@ -86,8 +83,16 @@ export function compileShadow(
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName } =
-        analyzeScript(scriptBody, scriptStart)
+    const {
+        imports,
+        types,
+        scope,
+        propsShapes,
+        diagnostics,
+        importedReactives,
+        propsLocalName,
+        watchLocalName,
+    } = analyzeScript(scriptBody, scriptStart)
     builder.raw(shadowPreamble(importedReactives))
     /* The peek helpers the async-interpolation wrap targets (ADR-0032): `$$peek` unwraps a promise
        sub-expression to its resolved value (`undefined` while pending) and `$$peekStream` reads an
@@ -112,15 +117,30 @@ export function compileShadow(
     if (propsLocalName !== undefined) {
         builder.raw(`declare function ${propsLocalName}<T = {}>(): (${propsType}) & T\n`)
     }
+    /* `watch` is re-typed with a trailing value-source overload: the real overloads
+       (`State`/socket/rpc/thunk) intersected with `<T>(source: T, handler: (value: T) => void)`.
+       A `watch(cell, handler)` source is projected to the cell's VALUE type (like every read),
+       so it never matches the real `State<T>` overload — the value-source form catches it and
+       types `handler`'s parameter as that value. Ordered after the real overloads (intersection
+       left-to-right), so a socket/rpc source still resolves to its specific frame/return type.
+       The real type is referenced through `typeof import(...)` (no value import to keep live), and
+       the binding uses the author's local alias — or the `watch` fallback for a bare/nested use
+       that isn't author-imported. */
+    const watchSpecifier = `${ABIDE_PACKAGE_NAME}/ui/watch`
+    builder.raw(
+        `declare const ${watchLocalName ?? 'watch'}: typeof import('${watchSpecifier}').watch & (<__WatchT>(source: __WatchT, handler: (value: __WatchT) => void) => () => void)\n`,
+    )
     const propsSpecifier = `${ABIDE_PACKAGE_NAME}/ui/props`
     for (const line of imports) {
-        /* The `props` import is replaced by the contextual `declare function` above;
-           emitting it too would be a duplicate-identifier error. Matched by EXACT specifier
+        /* The `props`/`watch` imports are replaced by the contextual declarations above;
+           emitting one too would be a duplicate-identifier error. Matched by EXACT specifier
            (either quote style, not a loose suffix match) so an unrelated user module merely
-           named `.../ui/props` survives verbatim. */
+           named `.../ui/props` (or `.../ui/watch`) survives verbatim. */
         if (
             line.text.includes(`from '${propsSpecifier}'`) ||
-            line.text.includes(`from "${propsSpecifier}"`)
+            line.text.includes(`from "${propsSpecifier}"`) ||
+            line.text.includes(`from '${watchSpecifier}'`) ||
+            line.text.includes(`from "${watchSpecifier}"`)
         ) {
             continue
         }
@@ -331,6 +351,11 @@ type ScriptAnalysis = {
        for the canonical import, `p` for `props as p`), or undefined when not imported. The
        `declare function` for `props` must target this name, not the canonical `'props'`. */
     propsLocalName: string | undefined
+    /* The LOCAL binding name the author's `watch` import is bound to (alias-safe), or undefined
+       when not imported. The shadow re-types `watch` under this name with a value-source
+       overload so the `watch(cell, handler)` form type-checks (the cell is projected to its
+       value, so the real State/socket/rpc overloads never match it). */
+    watchLocalName: string | undefined
 }
 
 /* Pushes a diagnostic for every author binding whose name starts with the reserved `$$`
@@ -451,6 +476,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             diagnostics,
             importedReactives: new Set(),
             propsLocalName: undefined,
+            watchLocalName: undefined,
         }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
@@ -462,10 +488,13 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     /* The local name bound to `props` (alias-safe): the key whose value is the canonical
        `'props'`. At most one — a file imports `props` from one specifier. */
     let propsLocalName: string | undefined
+    let watchLocalName: string | undefined
     for (const [local, canonical] of bindings.direct) {
         if (canonical === 'props') {
             propsLocalName = local
-            break
+        }
+        if (canonical === 'watch') {
+            watchLocalName = local
         }
     }
     /* The `$$` prefix is reserved for the compiler's injected runtime (`$$each`, `$$model`,
@@ -507,7 +536,16 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             scope.push(scopeLineFor(declaration, propsShapes, verbatim, span, bindings))
         }
     }
-    return { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName }
+    return {
+        imports,
+        types,
+        scope,
+        propsShapes,
+        diagnostics,
+        importedReactives,
+        propsLocalName,
+        watchLocalName,
+    }
 }
 
 /* Value-projects a nested control-flow `<script>` body the way `analyzeScript`

package/src/lib/ui/compile/lowerScript.ts

@@ -5,9 +5,11 @@ import { desugarSignals } from './desugarSignals.ts'
 import { identifierReferencePattern } from './identifierReferencePattern.ts'
 import { docAccessTransformer } from './lowerDocAccess.ts'
 import { signalRefsTransformer } from './renameSignalRefs.ts'
+import { reactiveImportBindings } from './resolveReactiveExport.ts'
 import { stripEffectsTransformer } from './stripEffects.ts'
 import { TS_PRINTER } from './TS_PRINTER.ts'
 import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
+import { wrapReactionCellSources } from './wrapReactionCellSources.ts'
 
 /* The `abide/ui/*` modules the reactive surface is imported from. An author's import of
    one is compiler-recognised and lowered, so its binding is often fully consumed — a plain
@@ -100,8 +102,24 @@ export function lowerScript(
         seedClassify,
         scriptBase,
     )
+    /* The local names bound to `watch` (alias-safe), and the full set of read-rewritten cell
+       names — together they let `wrapReactionCellSources` fold a `watch(cell, handler)` into
+       the thunk form BEFORE the read-lowering turns the cell reference into a value read. */
+    const watchLocalNames = new Set<string>()
+    for (const [local, canonical] of reactiveImportBindings(source).direct) {
+        if (canonical === 'watch') {
+            watchLocalNames.add(local)
+        }
+    }
+    const cellNames = new Set<string>([
+        ...stateNames,
+        ...derivedNames,
+        ...computedNames,
+        ...cellReadNames,
+    ])
     const result = ts.transform(source, [
         transformer,
+        wrapReactionCellSources(cellNames, watchLocalNames),
         signalRefsTransformer(
             stateNames,
             derivedNames,