@abide/abide 0.52.0 → 0.53.0

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

@@ -55,6 +55,10 @@ export function signalRefsTransformer(
        `computed` (see `desugarSignals`). A nearer lexical binding of the same name shadows
        them like any other signal. */
     cellReadNames: ReadonlySet<string> = new Set(),
+    /* The subset of `cellReadNames` that are BLOCKING `await` cells (ADR-0042), read through
+       `$$readCellBlocking(name)` (suspend-on-pending) instead of `$$readCell`. Non-empty only on
+       the CLIENT template lowering; the script pass and SSR keep it empty (`$$readCell`). */
+    blockingCellNames: ReadonlySet<string> = new Set(),
 ): ts.TransformerFactory<ts.SourceFile> {
     /* The signal names that a nested binding can shadow — only these matter for
        scope tracking, so we ignore every other local binding. */
@@ -162,6 +166,7 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
+                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
@@ -175,6 +180,7 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
+                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return replacement
@@ -393,6 +399,7 @@ function referenceFor(
     computedNames: ReadonlySet<string>,
     blockLocal: ReadonlySet<string> = new Set(),
     cellReadNames: ReadonlySet<string> = new Set(),
+    blockingCellNames: ReadonlySet<string> = new Set(),
 ): ts.Expression | undefined {
     if (blockLocal.has(name)) {
         return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(name), 'value')
@@ -402,6 +409,17 @@ function referenceFor(
     if (name === 'scope') {
         return ts.factory.createIdentifier('$$scope')
     }
+    /* A BLOCKING `await` cell → `$$readCellBlocking(name)` (ADR-0042): the throwing peek that
+       SUSPENDS the render region while pending, so an `await` binding reads as a resolved value
+       and its region withholds until it settles. Client template lowering only — `blockingCellNames`
+       is empty in the script pass and SSR, which keep the plain `$$readCell` peek below. */
+    if (blockingCellNames.has(name)) {
+        return ts.factory.createCallExpression(
+            ts.factory.createIdentifier('$$readCellBlocking'),
+            undefined,
+            [ts.factory.createIdentifier(name)],
+        )
+    }
     /* A `linked` / async `computed` cell → `$$readCell(name)`: one read shape that peeks an
        async cell and reads `.value` off a sync one. */
     if (cellReadNames.has(name)) {

package/src/lib/ui/compile/types/AnalyzedComponent.ts

@@ -28,6 +28,10 @@ export type AnalyzedComponent = {
        `computed`. Threaded to both back-ends so a template reference (`{draft}`) lowers to
        the unified cell read consistently on client and server. */
     cellReadNames: Set<string>
+    /* The subset of `cellReadNames` that are BLOCKING `await` cells (ADR-0042): a template-injected
+       `{await X}` cell or a script `computed(await …)`. The CLIENT back-end reads these via
+       `$$readCellBlocking` (suspend-on-pending) rather than `$$readCell`. */
+    blockingCellNames: Set<string>
     nodes: TemplateNode[]
     /* One entry per non-empty `<style>` in the template (in source order): the scope
        attribute its covered elements carry (annotated onto `nodes`) and the scoped

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

@@ -3,10 +3,12 @@ import { snippetPayload } from '../../shared/snippet.ts'
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { appendSnippet } from './appendSnippet.ts'
 import { assertClaimedText } from './assertClaimedText.ts'
 import { isComment } from './isComment.ts'
 import { parseRawNodes } from './parseRawNodes.ts'
+import { readTextOrSuspend } from './readTextOrSuspend.ts'
 
 const CLOSE = '/abide:html'
 
@@ -22,16 +24,36 @@ its parsed nodes go between an anchor (create), or the server-rendered nodes
 between `<!--abide:html-->`/`<!--/abide:html-->` markers are adopted (hydrate), and
 a change re-parses and swaps. A binding is text or raw for its lifetime (decided by
 its first value), so plain text — the common case — stays a cheap single node.
+
+A blocking `await` read that is pending throws a `SuspenseSignal` (ADR-0042): the
+interpolation SUSPENDS — it renders empty and withholds until the value resolves,
+never evaluating the surrounding expression against a pending `undefined`. The read
+tracked the cell, so the bind effect re-runs on settle. A suspend can only occur on a
+cold client render (on hydrate the warm-seed makes the cell `refreshing()`, not
+`pending()`, D4), and a suspended value is treated as text — its snippet/html shape is
+decided from the first resolved value.
 */
 // @documentation plumbing
 export function appendText(parent: Node, read: () => unknown, splitAlways = false): void {
+    /* Probe the first value once, tolerating a suspend (a pending blocking read) — a suspended
+       interpolation skips snippet/html detection and takes the text path, starting empty. */
+    let probe: unknown
+    let suspended = false
+    try {
+        probe = read()
+    } catch (signal) {
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        suspended = true
+    }
     /* A snippet call (`{row(args)}`) mounts its builder; a `html\`\`` value inserts
        raw markup; everything else is escaped text — decided by the first value. */
-    if (typeof snippetPayload(read()) === 'function') {
+    if (!suspended && typeof snippetPayload(probe) === 'function') {
         appendSnippet(parent, read)
         return
     }
-    if (rawHtmlString(read()) !== undefined) {
+    if (!suspended && rawHtmlString(probe) !== undefined) {
         appendRawHtml(parent, read)
         return
     }
@@ -39,8 +61,9 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
     if (hydration !== undefined) {
         const claimed = claimChild(hydration, parent)
         /* Nullish reads render as empty text, never the literal `"undefined"` — so a
-           pending async read (undefined-while-pending, ADR-0032 D3) shows nothing. */
-        const firstValue = read()
+           pending async read (undefined-while-pending, ADR-0032 D3) shows nothing. A blocking
+           read never suspends here (warm-seeded → `refreshing()`), so `probe` holds its value. */
+        const firstValue = probe
         const value = firstValue == null ? '' : String(firstValue)
         /* A value that first rendered empty produced NO server text node, so the cursor
            points at the following node (an element/comment) or past the end (null) — not a
@@ -77,16 +100,14 @@ export function appendText(parent: Node, read: () => unknown, splitAlways = fals
            at the end). */
         hydration.next.set(parent, isText ? node.nextSibling : claimed)
         effect(() => {
-            const next = read()
-            node.data = next == null ? '' : String(next)
+            node.data = readTextOrSuspend(read)
         })
         return
     }
     const node = document.createTextNode('')
     parent.appendChild(node)
     effect(() => {
-        const next = read()
-        node.data = next == null ? '' : String(next)
+        node.data = readTextOrSuspend(read)
     })
 }
 

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

@@ -2,9 +2,11 @@ import { rawHtmlString } from '../../shared/html.ts'
 import { snippetPayload } from '../../shared/snippet.ts'
 import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { appendSnippet } from './appendSnippet.ts'
 import { appendText } from './appendText.ts'
 import { parseRawNodes } from './parseRawNodes.ts'
+import { readTextOrSuspend } from './readTextOrSuspend.ts'
 
 /*
 A reactive `{expr}` interpolation mounted at a skeleton anchor comment (`<!--a-->`), used
@@ -39,14 +41,25 @@ export function appendTextAt(anchor: Node, read: () => unknown): void {
         return
     }
 
-    const first = read()
-    if (typeof snippetPayload(first) === 'function') {
+    /* Probe once, tolerating a suspend (a pending blocking read): a suspended interpolation skips
+       snippet/html detection and takes the text path, starting empty until the value resolves. */
+    let first: unknown
+    let suspended = false
+    try {
+        first = read()
+    } catch (signal) {
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        suspended = true
+    }
+    if (!suspended && typeof snippetPayload(first) === 'function') {
         const fragment = document.createDocumentFragment()
         appendSnippet(fragment, read)
         parent.insertBefore(fragment, anchor.nextSibling)
         return
     }
-    if (rawHtmlString(first) !== undefined) {
+    if (!suspended && rawHtmlString(first) !== undefined) {
         let nodes: Node[] = []
         effect(() => {
             for (const node of nodes) {
@@ -63,7 +76,11 @@ export function appendTextAt(anchor: Node, read: () => unknown): void {
     }
     const node = document.createTextNode('')
     parent.insertBefore(node, anchor.nextSibling)
+    /* Text/suspend handling shared with `appendText`'s bind via `readTextOrSuspend`: stringify the
+       value, show '' while a blocking read is pending (re-running on settle, since the read tracked
+       its cell), and coerce nullish to '' (never the literal "undefined") — keeping this create path
+       congruent with the hydrate path above, which delegates to `appendText`. */
     effect(() => {
-        node.data = String(read())
+        node.data = readTextOrSuspend(read)
     })
 }

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

@@ -1,6 +1,7 @@
 import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { reportHydrationDivergence } from '../runtime/reportHydrationDivergence.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 
 /* The attribute string an element carries for `value`, or `null` when absent — the present/absent +
    stringify semantics below, factored so the hydration compare and the write agree exactly. */
@@ -24,7 +25,21 @@ export function attr(element: Element, name: string, read: () => unknown): void
        invisible, since the effect always overwrites. */
     let hydrating = RENDER.hydration !== undefined
     effect(() => {
-        const value = read()
+        let value: unknown
+        try {
+            value = read()
+        } catch (signal) {
+            /* A pending blocking `await` read (ADR-0042) suspends this attribute: leave it
+               unset until the value resolves. The read tracked its cell, so this effect
+               re-runs on settle. A suspend can only occur on a cold client render (warm-seed
+               keeps a hydrating read `refreshing()`, never `pending()`), so the hydration
+               compare below is never reached while suspended. */
+            if (!(signal instanceof SuspenseSignal)) {
+                throw signal
+            }
+            element.removeAttribute(name)
+            return
+        }
         const next = attributeText(value)
         if (hydrating) {
             hydrating = false

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

@@ -8,6 +8,7 @@ import { RENDER } from '../runtime/RENDER.ts'
 import type { ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import type { State } from '../runtime/types/State.ts'
 import { withoutHydration } from '../runtime/withoutHydration.ts'
 import { state } from '../state.ts'
@@ -109,17 +110,10 @@ export function awaitBlock(
         activeKind = 'catch'
     }
 
-    /* Render a settled-or-pending result into the current generation. */
-    const render = (result: unknown): void => {
-        const gen = guard.token()
-        if (!isThenable(result)) {
-            settleThen(result) // warm-sync → resolved now, no flash
-            return
-        }
-        /* A then-branch is already mounted (a revalidation): keep it visible and update in
-           place when the new value settles, instead of blanking to pending and rebuilding —
-           this is the no-flash live-update path. A first load (or a prior pending/catch)
-           shows the pending branch (or detaches) while the promise is in flight. */
+    /* Show the pending branch (or detach when there is none), UNLESS a then-branch is already
+       mounted — a revalidation keeps it visible and updates in place when the new value settles
+       (the no-flash live-update path). Shared by an in-flight promise and a suspended subject read. */
+    const showPending = (): void => {
         if (activeKind !== 'then') {
             if (renderPending !== undefined) {
                 branch.place((host) => renderPending(host))
@@ -129,6 +123,18 @@ export function awaitBlock(
                 activeKind = undefined
             }
         }
+    }
+
+    /* Render a settled-or-pending result into the current generation. */
+    const render = (result: unknown): void => {
+        const gen = guard.token()
+        if (!isThenable(result)) {
+            settleThen(result) // warm-sync → resolved now, no flash
+            return
+        }
+        /* A first load (or a prior pending/catch) shows the pending branch while the promise is in
+           flight; a live then-branch stays put (see `showPending`). */
+        showPending()
         result.then(
             (value) => {
                 if (guard.live(gen)) {
@@ -296,8 +302,23 @@ export function awaitBlock(
         }
         /* Read the promise every subsequent run so an invalidate re-runs the block. ONLY this
            read is tracked (the branch builds untracked via `scope`), so the block re-runs only
-           when its promise source does, not on any branch-state change. */
-        render(promiseThunk())
+           when its promise source does, not on any branch-state change. A blocking `await` cell
+           embedded in the subject (`{#await loadMore(user.id)}` where `user` is an `await` cell)
+           throws a `SuspenseSignal` while pending (ADR-0042) — on a COLD client render the read
+           runs synchronously here, so withhold to the pending branch until it settles (mirroring
+           the local suspense withhold every other reading region does), rather than letting the
+           throw escape the build. The read tracked its cell, so this effect re-runs on resolve. */
+        let result: unknown
+        try {
+            result = promiseThunk()
+        } catch (signal) {
+            if (!(signal instanceof SuspenseSignal)) {
+                throw signal
+            }
+            showPending()
+            return
+        }
+        render(result)
     })
 }
 

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

@@ -13,6 +13,7 @@ import { buildDetachedRange } from './buildDetachedRange.ts'
 import { moveRange } from './moveRange.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
+import { withSuspense } from './withSuspense.ts'
 
 /*
 Keyed list binding — the runtime for `<template each key=>`. Each row is a content
@@ -119,6 +120,13 @@ export function each<T>(
         }
     }
 
+    /* Read the source, tolerating a pending blocking `await` read (a SuspenseSignal): treat a
+       suspend as an empty list — identical to the undefined-while-pending peek (ADR-0032 D3) — so
+       the each renders no rows until the source resolves. The read still tracked its cell, so the
+       driving effect re-runs on settle. */
+    const readSource = (): Iterable<T> | undefined =>
+        withSuspense<Iterable<T> | undefined>(items, undefined)
+
     let anchor: Node
     /* When hydrating, the first effect run must NOT reconcile — the rows it would
        build are already adopted in place below. */
@@ -128,7 +136,7 @@ export function each<T>(
         let position = 0
         /* An undefined source renders an empty list, not a throw — a `{#for x in promise}`
            whose lifted source peeks undefined while pending (ADR-0032 D3). */
-        for (const item of items() ?? []) {
+        for (const item of readSource() ?? []) {
             const key = keyOf(item)
             const row = buildRow(item, position) // claims the SSR row where it sits
             if (rows.has(key)) {
@@ -156,7 +164,7 @@ export function each<T>(
     effect(() => {
         /* Read (subscribe) every run, including the adopting one. Materialize a
            non-array iterable to an array so a generator yields fresh each run. */
-        const source = items()
+        const source = readSource()
         if (adopting) {
             adopting = false // rows already adopted in document order; nothing to move
             return

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

@@ -11,6 +11,7 @@ import { state } from '../state.ts'
 import { buildDetachedRange } from './buildDetachedRange.ts'
 import { removeRange } from './removeRange.ts'
 import type { EachRow } from './types/EachRow.ts'
+import { withSuspense } from './withSuspense.ts'
 
 /*
 Async keyed list — the runtime for `<template each await key=>`. Like `each`, but
@@ -113,7 +114,14 @@ export function eachAsync<T>(
             removeRange(row.start, row.end)
         }
         rows.clear()
-        const iterable = items() // read (subscribe) synchronously
+        /* Read (subscribe) the source synchronously, tolerating a pending blocking `await` read
+           embedded in it (a SuspenseSignal, ADR-0042): withhold — render no rows until it resolves,
+           exactly as sync `each` does. On a cold client render the read runs here at build; the
+           read tracked its cell, so this effect re-runs on settle. */
+        const iterable = withSuspense<AsyncIterable<T> | undefined>(items, undefined)
+        if (iterable === undefined) {
+            return
+        }
         const present = new Set<string>()
         let arrivals = 0 // stream arrival ordinal → each row's index
         const drain = async (): Promise<void> => {

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

@@ -0,0 +1,29 @@
+import { isAsyncCell } from '../../shared/isAsyncCell.ts'
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
+import { readCell } from './readCell.ts'
+
+/*
+The blocking-cell read the compiler lowers to `$$readCellBlocking(NAME)` for an `await`-marked
+cell (ADR-0042 D5.3). Exactly `readCell`, with one added rule ahead of it: a cell with no value
+*yet* throws a `SuspenseSignal` so the enclosing region SUSPENDS until the value resolves rather
+than rendering against `undefined`. This is what makes an `await` binding read as a resolved `T`
+(never `undefined`-while-pending) on both sides — the client mirrors the server flush barrier.
+
+The suspend is keyed on `cell.pending()` (in-flight AND no value), NOT `peek() === undefined`:
+  - a blocking cell that legitimately resolves to `undefined` is not pending, so it does not
+    suspend forever;
+  - a warm-seeded cell on hydrate is `refreshing()` (has value, in flight), not `pending()`, so it
+    reads its held value and adopts the SSR markup with no suspend and no flash (ADR-0042 D4).
+Everything past the pending gate — the throwing peek (error-with-no-retained-value → `AsyncCellError`
+to `{#try}`, a retained value winning over pending/error via SWR), a function call, or a `.value`
+read — is `readCell` verbatim, so the two reads can never drift.
+*/
+// @documentation plumbing
+export function readCellBlocking(cell: unknown): unknown {
+    /* No value yet → suspend the reading region (distinct from an error, which `readCell` routes). */
+    if (isAsyncCell(cell) && (cell as AsyncComputed<unknown>).pending()) {
+        throw new SuspenseSignal(cell as AsyncComputed<unknown>)
+    }
+    return readCell(cell)
+}

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

@@ -0,0 +1,21 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
+
+/*
+The text a reactive `{expr}` binding writes: the stringified value, or `''` while a blocking
+`await` read is pending — a `SuspenseSignal` (ADR-0042). Nullish stringifies to `''` (never the
+literal `"undefined"`), so a pending streaming read and a suspended blocking read both show nothing.
+A suspending read still tracked its cell before throwing, so the enclosing bind effect re-runs and
+fills in once the value resolves. Rethrows any non-suspense error unchanged.
+*/
+export function readTextOrSuspend(read: () => unknown): string {
+    let next: unknown
+    try {
+        next = read()
+    } catch (signal) {
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        return ''
+    }
+    return next == null ? '' : String(next)
+}

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

@@ -1,3 +1,5 @@
+import { effect } from '../effect.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { attr } from './attr.ts'
 import { on } from './on.ts'
 
@@ -19,7 +21,51 @@ export function spreadAttrs(
     exclude: string[] = [],
 ): void {
     const skip = new Set(exclude)
-    const object = source()
+    let object: Record<string, unknown>
+    try {
+        object = source()
+    } catch (signal) {
+        /* A spread over a PENDING blocking `await` read throws a `SuspenseSignal` here (ADR-0042):
+           its keys can't be enumerated yet. Binding the empty object now would create no `attr`/`on`
+           effects, so the attributes would never appear after the cell resolves — instead defer the
+           enumeration into a one-shot effect that re-runs on settle (the read tracked its cell). The
+           effect is pinned to this build's scope, so the `attr` binds it creates own their lifetime
+           correctly; a `spread` flag makes the enumeration fire exactly once (later value changes
+           re-read per key via `attr`, never re-enumerate). */
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        let spread = false
+        effect(() => {
+            let resolved: Record<string, unknown>
+            try {
+                resolved = source()
+            } catch (retry) {
+                if (!(retry instanceof SuspenseSignal)) {
+                    throw retry
+                }
+                return
+            }
+            if (spread) {
+                return
+            }
+            spread = true
+            bindKeys(element, source, resolved, skip)
+        })
+        return
+    }
+    bindKeys(element, source, object, skip)
+}
+
+/* Binds each own key of `object` onto `element`: an `on<event>` function attaches as a listener,
+   any other non-function value binds as a reactive attribute re-reading `source()[key]` per change.
+   A key in `skip` is left to its explicit binding. */
+function bindKeys(
+    element: Element,
+    source: () => Record<string, unknown>,
+    object: Record<string, unknown>,
+    skip: Set<string>,
+): void {
     for (const key in object) {
         if (skip.has(key)) {
             continue

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

@@ -1,3 +1,4 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { mountSwappableRange } from './mountSwappableRange.ts'
 import type { SwitchCase } from './types/SwitchCase.ts'
 
@@ -47,8 +48,24 @@ export function switchBlock(
         parent,
         /* A pending bare async subject (compiler-supplied `isPending`) selects no case — not
            even the default — so the block renders nothing until the cell settles, rather than
-           conflating "still loading" with a subject that matched the default. */
-        () => (isPending?.() === true ? -1 : select(subject())),
+           conflating "still loading" with a subject that matched the default. A blocking `await`
+           cell embedded in the subject or a `match` (a member access / compound the `isPending`
+           gate doesn't cover) throws a `SuspenseSignal` while pending (ADR-0042); select no case
+           until it settles, exactly as a bare async subject holds — the read tracked its cell, so
+           the swap effect re-runs on resolve. */
+        () => {
+            if (isPending?.() === true) {
+                return -1
+            }
+            try {
+                return select(subject())
+            } catch (signal) {
+                if (!(signal instanceof SuspenseSignal)) {
+                    throw signal
+                }
+                return -1
+            }
+        },
         (index) => {
             const chosen = index === -1 ? undefined : cases[index]
             return chosen && ((p) => chosen.render(p))

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

@@ -5,6 +5,7 @@ import { claimExpected } from '../runtime/claimExpected.ts'
 import { OWNER } from '../runtime/OWNER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import type { Boundary } from '../runtime/types/Boundary.ts'
 import type { State } from '../runtime/types/State.ts'
 import { withoutHydration } from '../runtime/withoutHydration.ts'
@@ -104,6 +105,15 @@ export function tryBlock(
             activeKind = 'try'
             errorCell = undefined
         } catch (error) {
+            /* A `SuspenseSignal` is "value pending", not an error, and must NEVER render `{:catch}`
+               (ADR-0042 D3, mirroring `flushEffects`, which refuses to route it to a boundary) — that
+               would flash the author's catch during loading and, since `rewatch` only arms on an
+               `AsyncCellError`, stick there forever. Every reading region withholds its own suspend
+               locally (post-ADR-0042 the `{#await}`/`{#each await}` subjects included), so this is
+               unreachable in a compiled template; rethrow defensively rather than mislabel it. */
+            if (error instanceof SuspenseSignal) {
+                throw error
+            }
             if (!hasCatch) {
                 throw error
             }

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

@@ -1,3 +1,4 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { mountSwappableRange } from './mountSwappableRange.ts'
 
 /*
@@ -26,7 +27,24 @@ export function when(
 ): void {
     mountSwappableRange(
         parent,
-        () => (isPending?.() === true ? 'pending' : condition() ? 'then' : 'else'),
+        () => {
+            if (isPending?.() === true) {
+                return 'pending'
+            }
+            /* A blocking `await` cell embedded in the condition — a member access or compound the
+               whole-subject `isPending` gate doesn't cover (`{#if !sources.length}`, `{#if user &&
+               await load()}`) — throws a `SuspenseSignal` while pending (ADR-0042). Withhold the
+               block (render neither branch) until it settles, exactly as a bare async subject holds;
+               the read tracked its cell, so the swap effect re-runs on resolve. */
+            try {
+                return condition() ? 'then' : 'else'
+            } catch (signal) {
+                if (!(signal instanceof SuspenseSignal)) {
+                    throw signal
+                }
+                return 'pending'
+            }
+        },
         (branch) => (branch === 'then' ? render : branch === 'else' ? renderElse : undefined),
         before,
         /* An async subject (compiler supplies `isPending`) can render a different branch on the

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

@@ -0,0 +1,22 @@
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
+
+/*
+Runs `read`, returning `fallback` when it SUSPENDS — a pending blocking `await` read throws a
+`SuspenseSignal` (ADR-0042). The reading region shows `fallback` until the value resolves; the
+throwing read subscribed the enclosing effect to the cell, so the effect re-runs and fills in on
+settle. Any non-suspense error propagates unchanged (a real rejection still reaches `{#try}`). The
+single place the `instanceof SuspenseSignal` swallow lives for a value-returning bind, so the read
+sites (`each`, `watch`, …) share one definition rather than copying the try/catch. Text binds use
+the sibling `readTextOrSuspend` (fallback `''` with String coercion); an attribute leaves itself
+unset inline (a side effect, not a fallback value).
+*/
+export function withSuspense<T>(read: () => T, fallback: T): T {
+    try {
+        return read()
+    } catch (signal) {
+        if (!(signal instanceof SuspenseSignal)) {
+            throw signal
+        }
+        return fallback
+    }
+}

package/src/lib/ui/runtime/SuspenseSignal.ts

@@ -0,0 +1,24 @@
+import type { AsyncComputed } from '../../shared/types/AsyncComputed.ts'
+
+/*
+The sentinel a compiled blocking read (`$$readCellBlocking`, an `await`-marked cell) raises
+when the cell has no value *yet* — "not resolved," not an error (ADR-0042 D3). It is a sibling
+of `AsyncCellError` but a DISTINCT class so the two are told apart by `instanceof`: a suspend is
+caught LOCALLY by the reading region — each DOM primitive (`appendText`, `attr`, `each`,
+`spreadAttrs`, `watch`, and the `when`/`switchBlock` condition) swallows it and withholds to an
+empty fallback, re-running on settle because the throwing read already subscribed the region's
+effect to the cell. It must never be handled as an error: `flushEffects` refuses to route a
+`SuspenseSignal` to a reactive `{#try}` (that would flash the author's `{:catch}` during loading),
+while an `AsyncCellError` still passes through. It carries the originating cell for diagnostics.
+Extends `Error` only to satisfy throw-an-Error lint and match `AsyncCellError`; it carries no
+`cause` — there is nothing wrong, the value is simply pending.
+*/
+export class SuspenseSignal extends Error {
+    readonly cell: AsyncComputed<unknown>
+
+    constructor(cell: AsyncComputed<unknown>) {
+        super('abide: suspense (value pending)')
+        this.name = 'SuspenseSignal'
+        this.cell = cell
+    }
+}