@abide/abide 0.52.0 → 0.54.0

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

@@ -91,10 +91,19 @@ export function lowerScript(
     derivedNames: Set<string>
     computedNames: Set<string>
     cellReadNames: Set<string>
+    /* Template-injected + script-level `await` cells (ADR-0042), read via `$$readCellBlocking`. */
+    blockingCellNames: Set<string>
     droppedReactiveImports: Set<string>
 } {
     const source = ts.createSourceFile('component.ts', scriptBody, ts.ScriptTarget.Latest, true)
-    const { transformer, stateNames, derivedNames, computedNames, cellReadNames } = desugarSignals(
+    const {
+        transformer,
+        stateNames,
+        derivedNames,
+        computedNames,
+        cellReadNames,
+        blockingCellNames: allBlockingNames,
+    } = desugarSignals(
         source,
         injectedCellNames,
         blockingCellNames,
@@ -185,6 +194,7 @@ export function lowerScript(
         derivedNames,
         computedNames,
         cellReadNames,
+        blockingCellNames: allBlockingNames,
         droppedReactiveImports,
     }
 }

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

@@ -0,0 +1,32 @@
+import ts from 'typescript'
+
+/*
+Lowers `x++` / `++x` / `x--` / `--x` on reactive state to a write of the stepped value,
+shared by the `$$model` doc path (lowerDocAccess) and the `$$writeCell` linked-cell path
+(renameSignalRefs). `makeRead`/`makeWrite` mirror `lowerCompoundAssignment`. The bare `++`
+can't survive onto the read form (`$$readCell(x)` / `$$model.read(...)` are calls, not
+lvalues), so it becomes an explicit write of `read ± 1`.
+
+Prefix evaluates to the NEW value, which is exactly what the write returns, so
+`write(read ± 1)` is correct as-is. POSTFIX must evaluate to the PREVIOUS value, so its
+result is corrected back by the opposite step (`x++` → `write(read + 1) - 1`) — no temp or
+closure, since the write returns the written value (`Cell.set` / `Doc.replace`). The
+correction is dead when the value is discarded (a statement `x++;`), so it costs nothing
+there.
+*/
+export function lowerUpdateExpression(
+    isPostfix: boolean,
+    isIncrement: boolean,
+    makeRead: () => ts.Expression,
+    makeWrite: (value: ts.Expression) => ts.Expression,
+): ts.Expression {
+    const step = isIncrement ? ts.SyntaxKind.PlusToken : ts.SyntaxKind.MinusToken
+    const write = makeWrite(
+        ts.factory.createBinaryExpression(makeRead(), step, ts.factory.createNumericLiteral(1)),
+    )
+    if (!isPostfix) {
+        return write
+    }
+    const correction = isIncrement ? ts.SyntaxKind.MinusToken : ts.SyntaxKind.PlusToken
+    return ts.factory.createBinaryExpression(write, correction, ts.factory.createNumericLiteral(1))
+}

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

@@ -1,5 +1,6 @@
 import ts from 'typescript'
-import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
+import { lowerCompoundAssignment } from './lowerCompoundAssignment.ts'
+import { lowerUpdateExpression } from './lowerUpdateExpression.ts'
 
 /*
 Rewrites references to a component's signal bindings into the document form the
@@ -55,6 +56,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. */
@@ -116,21 +121,19 @@ export function signalRefsTransformer(
                     !shadowed.has(node.left.text)
                 ) {
                     const target = node.left.text
-                    const right = ts.visitNode(node.right, visit) as ts.Expression
-                    if (node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
-                        return writeCellCall(target, right)
-                    }
-                    const binary = COMPOUND_ASSIGNMENT_OPERATORS.get(node.operatorToken.kind)
-                    if (binary !== undefined) {
-                        return writeCellCall(
-                            target,
-                            ts.factory.createBinaryExpression(cellReadCall(target), binary, right),
-                        )
+                    const lowered = lowerCompoundAssignment(
+                        node.operatorToken.kind,
+                        () => cellReadCall(target),
+                        ts.visitNode(node.right, visit) as ts.Expression,
+                        (value) => writeCellCall(target, value),
+                    )
+                    if (lowered !== undefined) {
+                        return lowered
                     }
                 }
                 /* `draft++` / `++draft` / `draft--` on a `linked` cell → a `$$writeCell` of the
-                   stepped value, mirroring the `+= 1` shape (the bare `++` would otherwise land
-                   on `$$readCell(draft)`, an invalid lvalue). */
+                   stepped value (the bare `++` would otherwise land on `$$readCell(draft)`, an
+                   invalid lvalue). */
                 if (
                     (ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) &&
                     (node.operator === ts.SyntaxKind.PlusPlusToken ||
@@ -139,17 +142,12 @@ export function signalRefsTransformer(
                     cellReadNames.has(node.operand.text) &&
                     !shadowed.has(node.operand.text)
                 ) {
-                    const step =
-                        node.operator === ts.SyntaxKind.PlusPlusToken
-                            ? ts.SyntaxKind.PlusToken
-                            : ts.SyntaxKind.MinusToken
-                    return writeCellCall(
-                        node.operand.text,
-                        ts.factory.createBinaryExpression(
-                            cellReadCall(node.operand.text),
-                            step,
-                            ts.factory.createNumericLiteral(1),
-                        ),
+                    const target = node.operand.text
+                    return lowerUpdateExpression(
+                        ts.isPostfixUnaryExpression(node),
+                        node.operator === ts.SyntaxKind.PlusPlusToken,
+                        () => cellReadCall(target),
+                        (value) => writeCellCall(target, value),
                     )
                 }
                 /* Shorthand `{ count }` → `{ count: $$model.count }` / `{ total: total.value }`,
@@ -162,6 +160,7 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
+                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
@@ -175,6 +174,7 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
+                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return replacement
@@ -393,6 +393,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 +403,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/seedTypeClassifierForRoot.ts

@@ -1,5 +1,6 @@
+import { cachedShadowProgram } from './cachedShadowProgram.ts'
 import { classifyInterpolationType } from './classifyInterpolationType.ts'
-import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+import type { ShadowProgram } from './createShadowProgram.ts'
 import { nodeAtShadowOffset } from './nodeAtShadowOffset.ts'
 import { shadowNaming } from './shadowNaming.ts'
 import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
@@ -18,25 +19,19 @@ as `state.computed` — either way the seed sub-expression maps back to source a
 own type), so the identical `sourceToShadowOffset → nodeAtShadowOffset → classifyInterpolation
 Type` pipeline the interpolation half uses resolves a seed with no node-finder variant.
 
-FAIL-OPEN, but NOT to `'sync'`: if the program can't build, the file has no shadow, the seed's
-location doesn't map, no node is found, or the checker throws, the classifier is absent /
-returns `undefined` — the signal the caller reads as "degrade to `isBareCallComputed`", NOT as
-"the seed is sync". Collapsing failure to `'sync'` (as the interpolation classifier does) would
-mis-route a failed stream seed to the lazy `derive` slot instead of today's syntax heuristic.
+FAIL-OPEN, but NOT to `'sync'`: if the program can't build (warned once per root by
+`cachedShadowProgram`), the file has no shadow, the seed's location doesn't map, no node is
+found, or the checker throws, the classifier is absent / returns `undefined` — the signal the
+caller reads as "degrade to `isBareCallComputed`", NOT as "the seed is sync". Collapsing failure
+to `'sync'` (as the interpolation classifier does) would mis-route a failed stream seed to the
+lazy `derive` slot instead of today's syntax heuristic.
 */
 export function seedTypeClassifierForRoot(
     cache: Map<string, ShadowProgram | undefined>,
     root: string,
     abidePath: string,
 ): SeedTypeClassifier | undefined {
-    if (!cache.has(root)) {
-        try {
-            cache.set(root, createShadowProgram(root))
-        } catch {
-            cache.set(root, undefined)
-        }
-    }
-    const shadowProgram = cache.get(root)
+    const shadowProgram = cachedShadowProgram(cache, root)
     if (shadowProgram === undefined) {
         return undefined
     }

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/compile/wrapReactionCellSources.ts

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { AbideCompileError } from './AbideCompileError.ts'
 
 /*
 Folds a cell-source `watch(source, handler)` into the auto-tracked thunk form
@@ -51,7 +52,7 @@ export function wrapReactionCellSources(
        expression is read ONCE as a plain value (outside any tracking scope) and handed to the
        runtime as a dead value: nothing subscribes, the reaction never fires. It can't be folded
        like a bare cell (a member access isn't a whole-cell subscription), so return the base
-       name to warn on and leave the source for the author to rewrite. */
+       name to REJECT on and point the author at the corrective forms. */
     function cellMemberBase(source: ts.Expression): string | undefined {
         if (
             (ts.isPropertyAccessExpression(source) || ts.isElementAccessExpression(source)) &&
@@ -95,19 +96,22 @@ export function wrapReactionCellSources(
                 )
                 return ts.factory.createCallExpression(node.expression, undefined, [thunk])
             }
-            /* Warn on the inert member-expression form `watch(s.foo, handler)` — it looks valid but
-               subscribes to nothing (see `cellMemberBase`). Not foldable; the fix is the author's. */
+            /* Reject the inert member-expression form `watch(s.foo, handler)` — it looks valid but
+               subscribes to nothing (see `cellMemberBase`), so the handler silently never fires. Not
+               foldable; a compile error turns the silent no-op into a caught mistake. A member of a
+               cell is never itself a cell (no per-property cells), so this can't reject a valid watch. */
+            const memberBase = sourceArg !== undefined ? cellMemberBase(sourceArg) : undefined
             if (
                 ts.isCallExpression(node) &&
                 ts.isIdentifier(node.expression) &&
                 watchLocalNames.has(node.expression.text) &&
                 node.arguments.length === 2 &&
                 sourceArg !== undefined &&
-                cellMemberBase(sourceArg) !== undefined
+                memberBase !== undefined
             ) {
                 const sourceText = sourceArg.getText(root)
-                console.warn(
-                    `[abide] \`watch(${sourceText}, …)\` does not track \`${sourceText}\` — a member access on a cell is read once as a plain value (abide has no per-property cells), so the reaction is inert. Wrap it in a thunk (\`watch(() => …(${sourceText}))\`) or watch the whole cell (\`watch(${cellMemberBase(sourceArg)}, v => …)\`).`,
+                throw new AbideCompileError(
+                    `[abide] \`watch(${sourceText}, …)\` does not track \`${sourceText}\` — a member access on a cell is read once as a plain value (abide has no per-property cells), so the reaction never fires. Wrap it in a thunk (\`watch(() => …(${sourceText}))\`) or watch the whole cell (\`watch(${memberBase}, v => …)\`).`,
                 )
             }
             return ts.visitEachChild(node, visit, context)

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

@@ -7,6 +7,7 @@ import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import type { ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
+import { SuspenseSignal } from '../runtime/SuspenseSignal.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
 import type { State } from '../runtime/types/State.ts'
 import { withoutHydration } from '../runtime/withoutHydration.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)
+}