@abide/abide 0.51.0 → 0.53.0

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

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
 
 /*
 Rewrites references to a component's signal bindings into the document form the
@@ -21,6 +22,21 @@ Exposed as a `ts.TransformerFactory`, so the script pipeline can chain it with
 `docAccessTransformer` over a SINGLE parsed tree (see `lowerScript`) instead of
 print-then-reparse between passes.
 */
+/* `$$readCell(name)` — the unified cell read (peek async / `.value` sync). */
+function cellReadCall(name: string): ts.Expression {
+    return ts.factory.createCallExpression(ts.factory.createIdentifier('$$readCell'), undefined, [
+        ts.factory.createIdentifier(name),
+    ])
+}
+
+/* `$$writeCell(name, value)` — the unified cell write (`.value =` sync / `.set(...)` async). */
+function writeCellCall(name: string, value: ts.Expression): ts.Expression {
+    return ts.factory.createCallExpression(ts.factory.createIdentifier('$$writeCell'), undefined, [
+        ts.factory.createIdentifier(name),
+        value,
+    ])
+}
+
 export function signalRefsTransformer(
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
@@ -39,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. */
@@ -87,6 +107,55 @@ export function signalRefsTransformer(
                 if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
                     return node
                 }
+                /* An assignment to a `linked` cell (a `cellReadNames` name) — its read form
+                   is `$$readCell(name)`, a call, so it can't sit on an assignment's left.
+                   Lower the write to `$$writeCell(name, value)`, which dispatches `.value =`
+                   (sync `State`) vs `.set(...)` (async `AsyncState`). A compound/logical
+                   assignment folds the current value in through the read form. `state` and
+                   `derived` writes stay on their own paths (`$$model.replace` / `.value =`). */
+                if (
+                    ts.isBinaryExpression(node) &&
+                    ts.isIdentifier(node.left) &&
+                    cellReadNames.has(node.left.text) &&
+                    !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),
+                        )
+                    }
+                }
+                /* `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). */
+                if (
+                    (ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) &&
+                    (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                        node.operator === ts.SyntaxKind.MinusMinusToken) &&
+                    ts.isIdentifier(node.operand) &&
+                    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),
+                        ),
+                    )
+                }
                 /* Shorthand `{ count }` → `{ count: $$model.count }` / `{ total: total.value }`,
                    unless a nearer scope shadows the name. */
                 if (ts.isShorthandPropertyAssignment(node) && !shadowed.has(node.name.text)) {
@@ -97,6 +166,7 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
+                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return ts.factory.createPropertyAssignment(node.name.text, replacement)
@@ -110,6 +180,7 @@ export function signalRefsTransformer(
                         computedNames,
                         blockLocal,
                         cellReadNames,
+                        blockingCellNames,
                     )
                     if (replacement !== undefined) {
                         return replacement
@@ -328,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')
@@ -337,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/compile/wrapReactionCellSources.ts

@@ -46,6 +46,23 @@ export function wrapReactionCellSources(
         return false
     }
 
+    /* The inert footgun: a member access (`s.foo`, `s['foo']`) whose base is a known cell.
+       abide has no per-property cells — the whole object lives in the one cell — so a member
+       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. */
+    function cellMemberBase(source: ts.Expression): string | undefined {
+        if (
+            (ts.isPropertyAccessExpression(source) || ts.isElementAccessExpression(source)) &&
+            ts.isIdentifier(source.expression) &&
+            cellNames.has(source.expression.text)
+        ) {
+            return source.expression.text
+        }
+        return undefined
+    }
+
     return (context) => (root) => {
         function visit(node: ts.Node): ts.Node {
             const [sourceArg, handlerArg] = ts.isCallExpression(node) ? node.arguments : []
@@ -78,6 +95,21 @@ 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. */
+            if (
+                ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                watchLocalNames.has(node.expression.text) &&
+                node.arguments.length === 2 &&
+                sourceArg !== undefined &&
+                cellMemberBase(sourceArg) !== 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 => …)\`).`,
+                )
+            }
             return ts.visitEachChild(node, visit, context)
         }
         return ts.visitNode(root, visit) as ts.SourceFile

package/src/lib/ui/createScope.ts

@@ -1,8 +1,11 @@
+import { decodeRefJson } from '../shared/decodeRefJson.ts'
+import { docSnapshotsSlot } from '../shared/docSnapshotsSlot.ts'
 import { computed } from './computed.ts'
 import { effect } from './effect.ts'
 import { linked } from './linked.ts'
 import { CURRENT_PATH } from './runtime/CURRENT_PATH.ts'
 import { createDoc } from './runtime/createDoc.ts'
+import { DOC_SEED } from './runtime/DOC_SEED.ts'
 import type { Cell } from './runtime/types/Cell.ts'
 import type { Doc } from './runtime/types/Doc.ts'
 import { state } from './state.ts'
@@ -43,6 +46,33 @@ export function createScope(
             : parent === undefined
               ? `scope-${nextId++}`
               : `${parent.id}.${nextId++}`
+    /* Doc-state warm-seed (client hydration only): a plain `state(initial)` re-runs its initializer
+       on the client, so a uuid/timestamp/random would diverge from the SSR HTML. The server snapshot
+       for this scope's render-path id is decoded here and consumed by `replace` on each slot's FIRST
+       write (the eager init), keeping the server value while the throwaway init is discarded. One-shot
+       — deleted on read so an SPA re-nav to the same path re-inits fresh; empty on the server. */
+    let pendingSeed: Map<string, unknown> | undefined
+    /* `DOC_SEED` is populated only on the client by `startClient` (empty on the server), so the read
+       needs no window guard — it mirrors the async-cell warm read. */
+    const encodedSeed = DOC_SEED[id]
+    if (encodedSeed !== undefined) {
+        delete DOC_SEED[id]
+        try {
+            pendingSeed = new Map(
+                Object.entries(decodeRefJson(encodedSeed) as Record<string, unknown>),
+            )
+        } catch {
+            /* A corrupt seed falls back to a cold init — the same failure mode as a warm cell. */
+        }
+    }
+    /* Server: register this scope's doc snapshot for the `__SSR__.docs` warm-seed, keyed by its
+       render-path id. Lazy — taken at render-return, after the synchronous state inits have run.
+       Only a rendered scope (stable render-path id) registers; a detached scope (counter id) and the
+       client never do. An empty/unused doc is dropped at the stamp, so a stateless scope costs only
+       the push. */
+    if (typeof window === 'undefined' && renderPath !== '') {
+        docSnapshotsSlot.get()?.entries.push({ id, take: () => document?.snapshot() })
+    }
     /* Adopted build teardowns (the reactivity stopper from the mount core). Disposed
        first and in reverse on teardown — so the one `dispose` runs the order the call sites
        hand-composed as `stop(); lexical.dispose()`. */
@@ -65,7 +95,18 @@ export function createScope(
         nextCellIndex: () => cellIndex++,
         parent,
         read: (path) => data().read(path),
-        replace: (path, value) => data().replace(path, value),
+        /* Consume-once seed adoption: on the client's hydrating build, the FIRST write to each seeded
+           slot is the eager `state(initial)` init — swap in the server value and drop the seed, so a
+           `state(uuid())` keeps the SSR value while its throwaway fresh init is discarded. Every later
+           write (a real reassignment) and every non-seeded path passes straight through. */
+        replace: (path, value) => {
+            if (pendingSeed?.has(path)) {
+                const seeded = pendingSeed.get(path)
+                pendingSeed.delete(path)
+                return data().replace(path, seeded)
+            }
+            return data().replace(path, value)
+        },
         add: (path, value) => data().add(path, value),
         remove: (path) => data().remove(path),
         apply: (patch) => data().apply(patch),

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/assertClaimedText.ts

@@ -1,3 +1,6 @@
+import { CURRENT_PATH } from '../runtime/CURRENT_PATH.ts'
+import { reportHydrationDivergence } from '../runtime/reportHydrationDivergence.ts'
+
 /*
 A text claim that MUST match the server's rendered text. On hydrate,
 appendStatic/appendText adopt a merged SSR text node and split it at the CLIENT
@@ -12,9 +15,16 @@ the following siblings' text AFTER it, so the value is exactly the leading slice
 mismatch means SSR and the client build disagree on the text here.
 */
 export function assertClaimedText(node: Text, value: string): void {
-    if (!node.data.startsWith(value)) {
-        throw new Error(
-            `[abide] hydration desync: expected server text beginning with ${JSON.stringify(value)} here, but the server DOM had ${JSON.stringify(node.data)} — SSR markup and the client build disagree on the text at this position.`,
-        )
+    if (node.data.startsWith(value)) {
+        return
+    }
+    /* Report on the `hydrate` channel with the render-path. With the channel on, keep hydrating
+       (re-split proceeds below on the client length) so one reload surfaces every text divergence;
+       off, the hard throw stays the default. A text miss is cursor-safe to continue past. */
+    if (!reportHydrationDivergence('text desync', { expected: value, server: node.data })) {
+        return
     }
+    throw new Error(
+        `[abide] hydration desync at ${CURRENT_PATH.current || '(root)'}: expected server text beginning with ${JSON.stringify(value)} here, but the server DOM had ${JSON.stringify(node.data)} — SSR markup and the client build disagree on the text at this position.`,
+    )
 }

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

@@ -1,4 +1,16 @@
 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. */
+function attributeText(value: unknown): string | null {
+    if (value === false || value === null || value === undefined) {
+        return null
+    }
+    return value === true ? '' : String(value)
+}
 
 /*
 Binds an element attribute to `read()`. A boolean true sets the bare attribute,
@@ -8,12 +20,38 @@ changed attribute touches the DOM.
 */
 // @documentation plumbing
 export function attr(element: Element, name: string, read: () => unknown): void {
+    /* Captured at bind time (inside the hydrating build) so the first effect run can compare the
+       server-rendered attribute before overwriting it — an attribute divergence is otherwise
+       invisible, since the effect always overwrites. */
+    let hydrating = RENDER.hydration !== undefined
     effect(() => {
-        const value = read()
-        if (value === false || value === null || value === undefined) {
+        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
+            const server = element.getAttribute(name)
+            if (server !== next) {
+                reportHydrationDivergence(`attr "${name}" desync`, { server, client: next })
+            }
+        }
+        if (next === null) {
             element.removeAttribute(name)
         } else {
-            element.setAttribute(name, value === true ? '' : String(value))
+            element.setAttribute(name, next)
         }
     })
 }

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)
+}