@abide/abide 0.35.0 → 0.36.0

package/README.md

@@ -1,153 +1,159 @@
 # abide
 
-**Write one function. Get a typed HTTP endpoint, a CLI, an MCP tool, and an OpenAPI operation — from the same line of code.**
+**One typed RPC declaration fans out to an HTTP route, a typed browser proxy, a CLI subcommand, an MCP tool, and an OpenAPI operation — built for humans and machines.**
 
-abide is a type-safe isomorphic framework built on web standards and Bun. You declare a verb once; the bundler swaps the runtime per side and projects that one declaration onto every surface — humans hit it over HTTP or the CLI, machines hit it over MCP, and you control which surfaces each verb exposes. It's a framework built for humans *and* machines.
+abide is an isomorphic framework on Bun: the same callable has the same name and behaviour on both sides, and the bundler swaps the runtime per side — a server handler in `src/server`, a `fetch` proxy in the browser. Server-render and hydrate the same `.abide` components, broadcast over multiplexed sockets, and expose every read to an agent — all in a single Bun runtime.
 
-- Zero runtime dependencies
-- A single runtime (Bun) in every mode — dev, build, and compiled binary
+- One dependency (`typescript`, for the type-checking shadow); `tailwindcss` + `bun-plugin-tailwind` are optional peers.
+- Runs on Bun `>= 1.3.0`. No bundler config, no server framework, no client router to wire up.
 
 ## Quick start
 
 ```sh
-bunx abide scaffold my-app   # scaffolds, installs, and starts the dev server
+bunx abide scaffold my-app   # scaffolds, installs deps, and (in a TTY) starts dev
 ```
 
-To see every surface live, clone the repo and run the kitchen-sink example — each page is runnable and documented:
+Or read the exhaustive demo:
 
 ```sh
 git clone https://github.com/briancray/abide
 cd abide && bun install
-cd examples/kitchen-sink && bun run dev
+cd examples/kitchen-sink && bun dev
 ```
 
+The whole public surface — every export, CLI command, route, env var, and the `.abide` grammar — is mapped in [`AGENTS.md`](./AGENTS.md).
+
 ## RPCs
 
-An RPC is a handler wrapped by its HTTP method — one export per file under `src/server/rpc/`. The file path is the URL; the schema validates args and projects the MCP tool, CLI flags, and OpenAPI operation. Standard Schema is the contract: zod, valibot, and arktype work unadapted.
+An RPC is one export per file under `src/server/rpc/`. The file path is the URL (`getMessages.ts` → `/rpc/getMessages`), and a [Standard Schema](https://standardschema.dev) (zod / valibot / arktype, unadapted) validates the args and projects every other surface.
 
 ```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 { history } from '../../store.ts'
 
-// query args arrive as strings — coerce in the schema
-const inputSchema = z.object({ room: z.string(), limit: z.coerce.number().default(50) })
+const inputSchema = z.object({ room: z.string() })
 
-export const getMessages = GET(
-    async ({ room, limit }) => json(await db.recentMessages(room, limit)),
-    { inputSchema },
-)
+export const getMessages = GET(({ room }) => json({ messages: history(room) }), { inputSchema })
 ```
 
-One declared verb fans out to every surface — this is the whole premise:
+That one declaration fans out:
 
 ```text
-       export const getMessages = GET(fn, { inputSchema })
-                                 │
-   ┌───────────────┬────────────┼──────────────┬────────────────┐
- SSR call      browser fetch    MCP tool      CLI subcommand   OpenAPI op
-cache(fn)()   fetch /rpc/...   getMessages   app get-messages  /openapi.json
-(in-process)  (typed proxy)  (read-only+schema) (schema→flags)   (described)
+                  getMessages   (one declaration)
+                        │
+   ┌──────────┬─────────┼─────────┬──────────────┐
+   ▼          ▼         ▼         ▼              ▼
+ SSR call   browser   MCP tool   CLI sub-     OpenAPI
+cache(fn)()  fetch   (read-only) command      operation
 ```
 
-The same callable is consumed differently per side — `cache(getMessages)({ room })` in-process, the swapped `fetch` in the browser, `.raw(args)` for a `Response`, `.stream(args)` for `tail()`. A schema gates the machine surfaces: it unlocks the CLI and (for read-only verbs) MCP; a mutating verb never auto-exposes to MCP — it needs an explicit `clients: { mcp: true }`. Per-verb `timeout` (504, on every surface) is distinct from the client-side `ABIDE_CLIENT_TIMEOUT`.
+The `inputSchema` unlocks the CLI and — because a `GET`/`HEAD` is read-only — an MCP tool. A mutating verb (`POST`/`PUT`/`PATCH`/`DELETE`) never auto-exposes to an agent; opt in with `clients: { mcp: true }`. Consume the verb four ways, all typed against the declaration: `cache(getMessages)({ room })` for an SSR-memoized in-process read, the bundler-swapped `getMessages({ room })` `fetch` proxy in the browser, `.raw(args)` for the untouched `Response`, and `.stream(args)` for a frame-by-frame `jsonl`/`sse` body.
 
-> Query args travel as strings — use `z.coerce.*` so numbers and booleans validate.
+> Query args travel as strings — use `z.coerce.*` for numbers and booleans. The per-verb `timeout` option fires a `504` on every surface and is distinct from the client-wide `ABIDE_CLIENT_TIMEOUT`.
 
 ## Sockets
 
-One broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — every socket multiplexes onto one ws at `/__abide/sockets`. A `schema` validates publishes, infers the frame type, and flips on the MCP/CLI read faces.
+A socket is one broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — `for await` it on the server, or read it reactively with `tail()` in a component — and every socket multiplexes onto one WebSocket at `/__abide/sockets`.
 
 ```ts
-// src/server/sockets/chat.ts
+// src/server/sockets/messages.ts
 import { socket } from '@abide/abide/server/socket'
 import { z } from 'zod'
 
-const schema = z.object({ id: z.string(), from: z.string(), text: z.string(), at: z.number() })
-
-// retain the last 100 frames, evict any older than an hour
-export const chat = socket({ schema, tail: 100, ttl: 3_600_000 })
-export type ChatMessage = z.infer<typeof schema>
+const schema = z.object({
+    id: z.string(),
+    room: z.string(),
+    from: z.string(),
+    text: z.string(),
+    at: z.number(),
+})
+
+// retain the last 100 frames; lazily evict any older than an hour
+export const messages = socket({ schema, tail: 100, ttl: 3_600_000 })
+export type Message = z.infer<typeof schema>
 ```
 
-For clients that can't speak the ws multiplex, each socket has an HTTP face at `/__abide/sockets/<name>` — `GET` returns the retained tail, `POST` publishes (gated by `clientPublish`, off by default).
+The schema validates every publish and flips on the read surfaces (a `messages-tail` MCP tool / CLI command). For clients that can't speak the ws multiplex, each socket has an HTTP face at `/__abide/sockets/messages`: `GET` returns the retained tail, `POST` publishes — gated by `clientPublish` (default `false`, so browsers publish through a validating verb instead).
 
 ## Components
 
-Components are `.abide` files — valid HTML with `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. Reactive state is reached through `scope()` (`scope().state(v)`, `scope().computed(fn)`); props are read by destructuring `props()` (`const { room } = props()`), and `effect` is in scope without import. This page reads the verb above through `cache()`, tails the socket live, and exercises most of the template grammar:
+A component is an `.abide` file: valid HTML with a `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. `scope()` is the sole reactive surface; `props`, `effect`, and `html` are in scope without import. This one imports the verb and socket above:
 
 ```html
 <script>
 import { cache } from '@abide/abide/shared/cache'
 import { tail } from '@abide/abide/ui/tail'
 import { getMessages } from '$server/rpc/getMessages.ts'
-import { publishChat } from '$server/rpc/publishChat.ts'
-import { chat } from '$server/sockets/chat.ts'
+import { sendMessage } from '$server/rpc/sendMessage.ts'
+import { messages } from '$server/sockets/messages.ts'
 import Avatar from '$ui/Avatar.abide'
 
-const { room } = props()                                           // typed via src/.abide/routes.d.ts
-const history = scope().computed(() => cache(getMessages)({ room })) // SSR snapshot + reactive refetch
-const latest = scope().computed(() => tail(chat))                  // re-renders on every new frame
+const { room } = props<{ room: string }>()
 
-let from = scope().state('alice')
-let text = scope().state('')
-let filter = scope().state('all')        // all | mine | others
-let onlyUnread = scope().state(false)
+let from = scope().state('alice')               // a writable cell — read/assign as a plain var
+let draft = scope().state('')
+let pinned = scope().state(false)
+let filter = scope().state('all')
+const live = scope().computed(() => tail(messages))   // re-renders on every new frame
 
 async function send(event: SubmitEvent) {
     event.preventDefault()
-    if (text.trim() === '') return
-    await publishChat({ from, text })                              // server validates, then broadcasts
-    text = ''
+    if (draft.trim() === '') return
+    await sendMessage({ room, from, text: draft })     // a mutating verb
+    draft = ''
 }
 </script>
 
-<template name="message" args={m}>                       <!-- snippet: a reusable builder -->
-    <li class="row"><Avatar name={m.from} /> <strong>{m.from}</strong>: {m.text}</li>
+<!-- a named snippet: a reusable builder, rendered like a function -->
+<template name="bubble" args={msg}>
+    <li><Avatar name={msg.from} /> <b>{msg.from}</b>: {msg.text}</li>
 </template>
 
+<h1>#{room}</h1>
+
 <form onsubmit={send}>
-    <input bind:value={from} placeholder="you" />
-    <input bind:value={text} placeholder="say something…" />
-    <label><input type="checkbox" bind:checked={onlyUnread} /> unread only</label>
-    <fieldset>
-        <label><input type="radio" bind:group={filter} value="all" /> all</label>
-        <label><input type="radio" bind:group={filter} value="mine" /> mine</label>
-    </fieldset>
-    <button type="submit" disabled={text.trim() === ''}>send</button>
+    <input bind:value={from} />
+    <input bind:value={draft} placeholder="message" />
+    <label><input type="checkbox" bind:checked={pinned} /> pin</label>
+    <label><input type="radio" bind:group={filter} value="all" /> all</label>
+    <label><input type="radio" bind:group={filter} value="mine" /> mine</label>
+    <button type="submit" disabled={draft.trim() === ''}>send</button>
 </form>
 
-<template if={latest}>
-    <p class="ping">latest from <strong>{latest.from}</strong></p>
+<template if={live}>
+    <p class="live">latest: {live.text}</p>
     <template else>
-        <p class="ping muted">no live messages yet</p>
+        <p>no messages yet</p>
     </template>
 </template>
 
 <template switch={filter}>
-    <template case={'mine'}><p>showing your messages</p></template>
-    <template default><p>showing every message</p></template>
+    <template case={'all'}><p>showing everyone</p></template>
+    <template case={'mine'}><p>showing {from}</p></template>
+    <template default><p>—</p></template>
 </template>
 
-<template await={history}>
-    <p>loading history…</p>
-    <template then="messages">
+<template await={cache(getMessages)({ room })}>
+    <p>loading…</p>
+    <template then="history">
         <ul>
-            <template each={messages} as="m" key="m.id">
-                {message(m)}                              <!-- render the snippet -->
+            <template each={history.messages} as="msg" key="msg.id">
+                {bubble(msg)}
             </template>
         </ul>
     </template>
-    <template catch="err">
-        <p class="error">{err.message}</p>
+    <template catch="error">
+        <p>failed: {error.message}</p>
     </template>
 </template>
 
 <style>
-    .row { display: flex; gap: 0.5rem; }
-    .muted { color: #94a3b8; }
-    .error { color: #dc2626; }
+    .live {
+        font-weight: 600;
+    }
 </style>
 ```
 

package/package.json

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

package/src/lib/shared/cache.ts

@@ -24,6 +24,7 @@ import type { CacheStore } from './types/CacheStore.ts'
 import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
 import type { RemoteFunction } from './types/RemoteFunction.ts'
 import type { Subscribable } from './types/Subscribable.ts'
+import { withCacheManaged } from './withCacheManaged.ts'
 
 type AnyRemote<Args, Return> = RemoteFunction<Args, Return> | RawRemoteFunction<Args>
 type Producer<Args, Return> = (args?: Args) => Promise<Return>
@@ -309,8 +310,12 @@ function invokeProducer<Args, Return>(
     }
     /* Miss: time the producer run — where a request's time actually goes (an
        external fetch, a computation). Producer path only; the remote path must
-       keep its own promise so getRemoteMeta can read the recorded Request. */
-    const promise = cacheLog.trace<Return>(`cache ${key}`, () => producer(args))
+       keep its own promise so getRemoteMeta can read the recorded Request. The
+       producer runs cache-managed so a bare RPC inside it isn't scope-bound — the
+       cache coalesces and owns this flight. */
+    const promise = cacheLog.trace<Return>(`cache ${key}`, () =>
+        withCacheManaged(() => producer(args)),
+    )
     registerEntry(store, key, promise, options, undefined, () => producer(args))
     return promise
 }
@@ -326,7 +331,9 @@ function invokeRemote<Args>(
     if (existing) {
         return shareable(existing.promise as Promise<Response>)
     }
-    const promise = rawFn(args as Args)
+    /* Cache-managed: the shared flight isn't bound to the reader that triggered the
+       miss, so its scope disposing can't abort a request other readers still join. */
+    const promise = withCacheManaged(() => rawFn(args as Args))
     const request = getRemoteMeta(promise)
     if (!request) {
         throw new Error(

package/src/lib/shared/cacheManagedSlot.ts

@@ -0,0 +1,10 @@
+/*
+Set while cache() synchronously invokes the underlying remote/producer, so the
+client's currentAbortSignal skips scope-binding for cache-managed calls. The cache
+coalesces one in-flight request across every reader and owns its lifetime (it
+evicts the entry when the request rejects), so a single reader navigating away must
+not abort a flight the others still depend on. A plain boolean — cache invokes the
+underlying call synchronously and never re-enters across an await. Harmless on the
+server, where there is no reactive observer to bind anyway.
+*/
+export const cacheManagedSlot: { active: boolean } = { active: false }

package/src/lib/shared/withCacheManaged.ts

@@ -0,0 +1,18 @@
+import { cacheManagedSlot } from './cacheManagedSlot.ts'
+
+/*
+Runs `invoke` with cacheManagedSlot flagged, so any RPC fired synchronously inside
+it (the cache's underlying remote/producer call) skips reactive scope-binding — the
+cache, not the calling reader, owns the shared flight's lifetime. Save/restore keeps
+it correct under nesting (a producer that itself reads cache). The fetch is fired
+synchronously and the flag clears before the await, so it never spans the network.
+*/
+export function withCacheManaged<T>(invoke: () => T): T {
+    const previous = cacheManagedSlot.active
+    cacheManagedSlot.active = true
+    try {
+        return invoke()
+    } finally {
+        cacheManagedSlot.active = previous
+    }
+}

package/src/lib/ui/dom/awaitBlock.ts

@@ -3,6 +3,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { discardBoundary } from './discardBoundary.ts'
 import { enterNamespace } from './enterNamespace.ts'
 
@@ -41,6 +42,9 @@ export function awaitBlock(
     before: Node | null = null,
 ): void {
     const hydration = RENDER.hydration
+    /* The live branch's scope, registered with the owner so it disposes on owner
+       teardown — not only when a settle/re-run swaps branches via detach. */
+    const group = scopeGroup()
     let active: { nodes: Node[]; dispose: () => void } | undefined
     let anchor: Node | undefined
     let first = true
@@ -67,8 +71,8 @@ export function awaitBlock(
     const place = (build: (parent: Node) => void): void => {
         detach()
         const fragment = document.createDocumentFragment()
-        const dispose = enterNamespace(anchor?.parentNode ?? parent, () =>
-            scope(() => build(fragment)),
+        const dispose = group.track(
+            enterNamespace(anchor?.parentNode ?? parent, () => scope(() => build(fragment))),
         )
         const nodes = [...fragment.childNodes]
         ;(anchor?.parentNode ?? parent).insertBefore(fragment, anchor ?? null)
@@ -112,7 +116,7 @@ export function awaitBlock(
     const adopt = (open: Node | null, build: (parent: Node) => void): void => {
         const cursor = hydration as NonNullable<typeof hydration>
         cursor.next.set(parent, open?.nextSibling ?? null)
-        const dispose = scope(() => build(parent))
+        const dispose = group.track(scope(() => build(parent)))
         const close = claimChild(cursor, parent)
         cursor.next.set(parent, close?.nextSibling ?? null)
         const nodes: Node[] = []

package/src/lib/ui/dom/each.ts

@@ -1,9 +1,9 @@
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { claimExpected } from '../runtime/claimExpected.ts'
-import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { enterNamespace } from './enterNamespace.ts'
 import { moveRange } from './moveRange.ts'
 import { removeRange } from './removeRange.ts'
@@ -36,6 +36,9 @@ export function each<T>(
     before: Node | null = null,
 ): void {
     const rows = new Map<string, EachRow>()
+    /* Each row's scope, registered with the owner so every live row disposes on owner
+       teardown (the effect's own disposer only unsubscribes it from `items()`). */
+    const group = scopeGroup()
 
     /* Build a row's range. Hydrate mode (only while the claim cursor is active —
        read fresh, since a row built by a post-hydration reconcile must create, not
@@ -47,7 +50,7 @@ export function each<T>(
         if (hydration !== undefined) {
             const start = claimExpected(hydration, parent, 'each row start marker')
             hydration.next.set(parent, start.nextSibling)
-            const dispose = scope(() => render(parent, item))
+            const dispose = group.track(scope(() => render(parent, item)))
             const end = claimExpected(hydration, parent, 'each row end marker')
             hydration.next.set(parent, end.nextSibling)
             return { start, end, dispose }
@@ -58,7 +61,9 @@ export function each<T>(
         pending.appendChild(start)
         /* Build under `parent`'s foreign namespace so foreign row elements (svg/math)
            built into the detached fragment are namespaced, not built as HTML. */
-        const dispose = enterNamespace(parent, () => scope(() => render(pending, item)))
+        const dispose = group.track(
+            enterNamespace(parent, () => scope(() => render(pending, item))),
+        )
         pending.appendChild(end)
         return { start, end, dispose, pending }
     }
@@ -146,16 +151,4 @@ export function each<T>(
             RENDER.hydration = previousHydration
         }
     })
-
-    /* Dispose every row still live when the enclosing scope tears down (the effect's
-       own disposer only unsubscribes it from `items()`). The host's DOM is cleared by
-       `mount`, so disposal need not remove the nodes. */
-    if (OWNER.current !== undefined) {
-        OWNER.current.push(() => {
-            for (const row of rows.values()) {
-                row.dispose()
-            }
-            rows.clear()
-        })
-    }
 }

package/src/lib/ui/dom/eachAsync.ts

@@ -3,6 +3,7 @@ import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { enterNamespace } from './enterNamespace.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
@@ -32,6 +33,9 @@ export function eachAsync<T>(
     before: Node | null = null,
 ): void {
     const rows = new Map<string, EachRow>()
+    /* Each row's (and the error branch's) scope, registered with the owner so they
+       dispose on owner teardown; the block's own teardown only stops the stream. */
+    const group = scopeGroup()
     const hydration = RENDER.hydration
     const anchor = document.createTextNode('')
     if (hydration !== undefined) {
@@ -46,8 +50,8 @@ export function eachAsync<T>(
         const end = document.createComment(']')
         const fragment = document.createDocumentFragment()
         fragment.appendChild(start)
-        const dispose = enterNamespace(anchor.parentNode ?? parent, () =>
-            scope(() => build(fragment)),
+        const dispose = group.track(
+            enterNamespace(anchor.parentNode ?? parent, () => scope(() => build(fragment))),
         )
         fragment.appendChild(end)
         /* Insert via the anchor's LIVE parent: when this `each` is a bare child of a
@@ -127,18 +131,13 @@ export function eachAsync<T>(
     })
 
     /* Stop the live stream when the enclosing scope tears down: bump the generation so
-       the drain abandons its loop, `return()` the iterator to release the source, drop
-       the error branch, and dispose every surviving row. */
+       the drain abandons its loop and `return()` the iterator to release the source. The
+       rows and error branch are disposed by the group (their scopes were tracked). */
     if (OWNER.current !== undefined) {
         OWNER.current.push(() => {
             generation += 1
             iterator?.return?.(undefined)?.catch(() => undefined)
             iterator = undefined
-            clearError()
-            for (const row of rows.values()) {
-                row.dispose()
-            }
-            rows.clear()
         })
     }
 }

package/src/lib/ui/dom/switchBlock.ts

@@ -1,6 +1,7 @@
 import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { clearBetween } from './clearBetween.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
@@ -26,6 +27,9 @@ export function switchBlock(
     before: Node | null = null,
 ): void {
     const hydration = RENDER.hydration
+    /* The live case's scope, registered with the owner so it disposes on owner
+       teardown — not only when the subject switches cases via clearBetween. */
+    const group = scopeGroup()
     let dispose: (() => void) | undefined
     let activeIndex: number
     let end: Comment
@@ -46,7 +50,7 @@ export function switchBlock(
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
         if (chosen !== undefined) {
-            dispose = scope(() => chosen.render(parent)) // claim the SSR nodes in place
+            dispose = group.track(scope(() => chosen.render(parent))) // claim the SSR nodes in place
         }
         end = openMarker(parent, ']')
     } else {
@@ -54,7 +58,7 @@ export function switchBlock(
         activeIndex = select(subject())
         const chosen = caseAt(activeIndex)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, (p) => chosen.render(p))
+            dispose = group.track(fillBefore(end, (p) => chosen.render(p)))
         }
     }
 
@@ -68,7 +72,7 @@ export function switchBlock(
         activeIndex = index
         const chosen = caseAt(index)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, (p) => chosen.render(p))
+            dispose = group.track(fillBefore(end, (p) => chosen.render(p)))
         }
     })
 }

package/src/lib/ui/dom/tryBlock.ts

@@ -1,6 +1,7 @@
 import { claimChild } from '../runtime/claimChild.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { discardBoundary } from './discardBoundary.ts'
 import { enterNamespace } from './enterNamespace.ts'
 
@@ -28,20 +29,30 @@ export function tryBlock(
     renderCatch?: (parent: Node, error: unknown) => void,
     before: Node | null = null,
 ): void {
-    /* Run a void build under a fresh ownership scope; on throw, tear down the partial
-       effects/listeners it registered and rethrow so the caller can fall back. */
+    /* The guarded subtree's scope, registered with the owner so it disposes on owner
+       teardown. The block renders once, so there is at most one tracked subtree (the
+       try branch, or the catch branch if try threw). */
+    const group = scopeGroup()
+    /* Run a void build under a fresh ownership scope. On success, hand its disposers to
+       the group so the subtree tears down with the owner (they were previously dropped —
+       the leak). On throw, tear down the partial build now and rethrow so the caller can
+       fall back to the catch branch. */
     const guard = (build: () => void): void => {
         const previous = OWNER.current
         const disposers: Array<() => void> = []
         OWNER.current = disposers
+        const disposeAll = (): void => {
+            for (let index = disposers.length - 1; index >= 0; index -= 1) {
+                disposers[index]?.()
+            }
+        }
         try {
             build()
             OWNER.current = previous
+            group.track(disposeAll)
         } catch (error) {
             OWNER.current = previous
-            for (let index = disposers.length - 1; index >= 0; index -= 1) {
-                disposers[index]?.()
-            }
+            disposeAll()
             throw error
         }
     }

package/src/lib/ui/dom/when.ts

@@ -1,6 +1,7 @@
 import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
 import { clearBetween } from './clearBetween.ts'
 import { fillBefore } from './fillBefore.ts'
 import { openMarker } from './openMarker.ts'
@@ -28,6 +29,9 @@ export function when(
 ): void {
     const hydration = RENDER.hydration
     const chosenFor = (branch: 'then' | 'else') => (branch === 'then' ? render : renderElse)
+    /* The live branch's scope, registered with the owner so it disposes on owner
+       teardown — not only on a branch flip via clearBetween. */
+    const group = scopeGroup()
     let dispose: (() => void) | undefined
     let activeBranch: 'then' | 'else'
     let end: Comment
@@ -40,7 +44,7 @@ export function when(
         activeBranch = condition() ? 'then' : 'else'
         const chosen = chosenFor(activeBranch)
         if (chosen !== undefined) {
-            dispose = scope(() => chosen(parent)) // content claims the SSR nodes in place
+            dispose = group.track(scope(() => chosen(parent))) // content claims the SSR nodes in place
         }
         end = openMarker(parent, ']')
     } else {
@@ -48,7 +52,7 @@ export function when(
         activeBranch = condition() ? 'then' : 'else'
         const chosen = chosenFor(activeBranch)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, chosen)
+            dispose = group.track(fillBefore(end, chosen))
         }
     }
 
@@ -62,7 +66,7 @@ export function when(
         activeBranch = branch
         const chosen = chosenFor(branch)
         if (chosen !== undefined) {
-            dispose = fillBefore(end, chosen)
+            dispose = group.track(fillBefore(end, chosen))
         }
     })
 }