@abide/abide 0.52.0 → 0.53.0

package/AGENTS.md

@@ -176,13 +176,19 @@ Mustache `{#…}` blocks, not `<template>`. The rendered blocks are
 | `{#try}` / `{:catch}` / `{:finally}` / `{/try}` | Render error boundary. |
 | `{#snippet name(args)}…{/snippet}` | Reusable builder; called `{name(args)}`. |
 
-Async reads have no ceremony: the **bare call in an interpolation**
-(`{getMessages({ limit })}`) is the documented default — a peek that reads
-`undefined` while pending (auto-streaming on SSR), composing with `?? fallback`,
-`?.`, `{#if}`, and attributes; pair it with `.pending(...)` / `.error(...)`
-probes. `{await fn()}` is an inline read that blocks SSR until the value is in the
-HTML. `{#await}` is the opt-in for branch structure and `{:then}` narrowing — not
-the default.
+Async reads have no ceremony, and `await` is the marker that picks the mode
+(ADR-0042). A **bare call in an interpolation** (`{getMessages({ limit })}`)
+*streams*: a peek that reads `undefined` while pending (typed `T | undefined`,
+auto-streaming on SSR), composing with `?? fallback`, `?.`, `{#if}`, and
+attributes; pair it with `.pending(...)` / `.error(...)` probes. `{await fn()}`
+means *resolved*: the server blocks the flush AND the client **suspends** the
+reading region (renders nothing) until it settles, so the value is never pending
+at the read — `{(await fn()).field}` needs no `?.` and never derefs a pending
+`undefined`. A refetch never re-suspends (stale-while-revalidate); warm-seed keeps
+a hydrating read `refreshing()`, so no flash. (Consequently a no-`await` `async`
+thunk — `computed(async () => getFoo())` — is a *streaming* cell, not blocking;
+`await` is the sole blocking marker.) `{#await}` is the opt-in for branch structure
+and `{:then}` narrowing — not the default.
 
 Components are capitalised tags; the content nested in a component renders where
 it calls `{children()}` (`{#if children}{children()}{:else}…{/if}` is the
@@ -444,6 +450,9 @@ Compiler-emitted; an author never imports these directly.
   read, with legible authored-scope errors.
 - `abide/ui/dom/readCell` — unified read of a `computed`/`linked`/derive reference
   (async → throwing peek, function → call, sync → `.value`).
+- `abide/ui/dom/readCellBlocking` — the blocking (`await`) variant of `readCell`: on a
+  pending cell it throws a suspense signal so the reading region withholds until the
+  value resolves, rather than reading `undefined` (client template lowering; ADR-0042).
 - `abide/ui/dom/writeCell` — unified write of a `linked` reference from an author
   assignment (async → `.set`, sync → `.value =`).
 - `abide/ui/dom/cellPending` — whether a control-flow subject is a still-loading async

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # abide
 
+## 0.53.0
+
+### Minor Changes
+
+- shadow narrows streaming cells to T|undefined + D7 barrier tripwire (ADR-0042 D5.2/D7) ([`034a384`](https://github.com/briancray/abide/commit/034a384bdfb5b482f818de757e10c2e2e88ac52c))
+- suspend interpolations/attributes on a pending blocking read (ADR-0042) ([`88da27c`](https://github.com/briancray/abide/commit/88da27c998666b7cca9149effd5f171f3adca8d1))
+- flip async-thunk blocking marker + emit $$readCellBlocking on the client (ADR-0042 D5/D6) ([`a3468fe`](https://github.com/briancray/abide/commit/a3468feacbb67ac9cd337ffa2e220b10af309324))
+- dormant client-suspense foundation for await-means-resolved (ADR-0042) ([`b5f6104`](https://github.com/briancray/abide/commit/b5f6104c41ea1d57d3347ae007cdb1b316a09784))
+- complete the client suspense withhold surface across all template effects (ADR-0042) ([`c5db314`](https://github.com/briancray/abide/commit/c5db314fa3e0ce18294f609be5fb43e5128970d0))
+- fa7bfed: `await` now means "resolved" for a cell and its dependents, with the client suspending to mirror the server flush barrier (ADR-0042). A blocking `await` read (`{await foo()}`, `const x = state.computed(await …)`, `{#if await …}`) reads as a resolved value on both sides: the server already blocks the flush until it settles, and the client now **withholds the reading region** (interpolation, attribute, `{#if}`/`{#each}`/`{#switch}` block) until the value resolves rather than rendering against a pending `undefined`. So `{sources.length}` on an `await` binding no longer needs `?.` and no longer crashes while pending — the region simply shows nothing until it settles, then reveals. After the first resolution a refetch never re-suspends (stale-while-revalidate); on hydrate the warm-seed keeps the read `refreshing()`, never `pending()`, so there is no flash.
+
+    **Breaking:**
+
+    - **The async modifier alone is no longer a blocking marker — `await` is.** `computed(async () => getFoo())` (an `async` thunk with no top-level `await`) now creates a **streaming** cell (ships pending, resolves on the client) instead of a blocking one. Add `await` — `computed(async () => await getFoo())` — to keep the blocking/inline-SSR behavior. `computed(await …)` and `computed(async () => await …)` are unchanged (blocking).
+    - **A streaming (no-`await`) async `computed`/`linked` now types as `T | undefined`.** Its read is honestly pending-able, so guard it with `?.`/`??` (matching the runtime). A blocking `await` binding stays `T`.
+
+    No new public API — the change is in how `await` lowers and types.
+
+### Patch Changes
+
+- document await-means-resolved (ADR-0042) ([`16ec341`](https://github.com/briancray/abide/commit/16ec341a6ea7da509919b37a1cdcc2f237e04c1c))
+- close await-suspense gaps and simplify the boundary (ADR-0042 review) ([`7f9fcbb`](https://github.com/briancray/abide/commit/7f9fcbbec862eba6da3103a6aca77d505ef6f58d))
+- type {:catch} bindings as unknown, not any (ADR-0042) ([`9a91522`](https://github.com/briancray/abide/commit/9a915229caf92914b5bcd9e5625153831783049d))
+- withhold pending blocking reads in {#await}/{#for await} subjects (ADR-0042) ([`e58b538`](https://github.com/briancray/abide/commit/e58b538f477c2bfcec654fd1a7aab65466cc956c))
+
 ## 0.52.0
 
 ### Minor Changes

package/README.md

@@ -124,14 +124,16 @@ async function send() {
 <section class="chat" class:empty={limit === 0} style:--rows={shown} {...rootAttrs}>
     <h1>{title}</h1>
 
-    <!-- Async reads have no ceremony: the bare call is the way. It peeks
-         `undefined` while pending, so it composes with `??` and the probes. -->
+    <!-- A bare read STREAMS: it peeks `undefined` while pending, so it composes
+         with `??` and the probes. `await` is the marker for the other mode. -->
     <p class:loading={getMessages.pending({ limit })}>
         {getMessages({ limit })?.length ?? 0} messages
         {#if getMessages.error({ limit })}<span>failed to load</span>{/if}
     </p>
 
-    <!-- `{await}` is an inline read: it blocks SSR until the value is in the HTML. -->
+    <!-- `{await}` means RESOLVED: the server blocks the flush and the client suspends
+         this region until it settles, so the value is never pending at the read (no `?.`)
+         — the region just shows nothing, then reveals. -->
     <small>today: {await countToday()}</small>
 
     <!-- `{#await}` is the explicit opt-in — a distinct pending branch and `{:then}` narrowing. -->
@@ -150,7 +152,7 @@ async function send() {
             <p>raise the limit</p>
         {/if}
     {:catch err}
-        <p>{err.message}</p>
+        <p>{err instanceof Error ? err.message : String(err)}</p>
     {:finally}
         <hr />
     {/await}
@@ -171,7 +173,7 @@ async function send() {
     {#try}
         <p>{risky()}</p>
     {:catch e}
-        <p>widget crashed: {e.message}</p>
+        <p>widget crashed: {e instanceof Error ? e.message : String(e)}</p>
     {:finally}
         <span>rendered</span>
     {/try}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.52.0",
+    "version": "0.53.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -95,6 +95,7 @@
         "./ui/dom/spreadAttrs": "./src/lib/ui/dom/spreadAttrs.ts",
         "./ui/dom/readCall": "./src/lib/ui/dom/readCall.ts",
         "./ui/dom/readCell": "./src/lib/ui/dom/readCell.ts",
+        "./ui/dom/readCellBlocking": "./src/lib/ui/dom/readCellBlocking.ts",
         "./ui/dom/writeCell": "./src/lib/ui/dom/writeCell.ts",
         "./ui/dom/cellPending": "./src/lib/ui/dom/cellPending.ts",
         "./ui/runtime/withPath": "./src/lib/ui/runtime/withPath.ts",

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

@@ -56,6 +56,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: stri
     { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs', alias: '$$spreadAttrs' },
     { name: 'readCall', specifier: 'ui/dom/readCall', alias: '$$readCall' },
     { name: 'readCell', specifier: 'ui/dom/readCell', alias: '$$readCell' },
+    { name: 'readCellBlocking', specifier: 'ui/dom/readCellBlocking', alias: '$$readCellBlocking' },
     { name: 'writeCell', specifier: 'ui/dom/writeCell', alias: '$$writeCell' },
     { name: 'cellPending', specifier: 'ui/dom/cellPending', alias: '$$cellPending' },
     { name: 'withPath', specifier: 'ui/runtime/withPath', alias: '$$withPath' },

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

@@ -120,6 +120,7 @@ export function analyzeComponent(
         derivedNames,
         computedNames,
         cellReadNames,
+        blockingCellNames: allBlockingCellNames,
         droppedReactiveImports,
     } = lowerScript(
         fullScriptBody,
@@ -142,6 +143,7 @@ export function analyzeComponent(
         derivedNames,
         computedNames,
         cellReadNames,
+        blockingCellNames: allBlockingCellNames,
         nodes,
         styles,
         /* Hydration adopts every block in place — including `await`, which resumes

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

@@ -29,7 +29,8 @@ export function compileComponent(
        a direct caller (tests) omits it and the front-end runs here — threading `classify` and
        `seedClassify` so type-directed interpolation + cell lowering happen on this path too. */
     const resolved = analyzed ?? analyzeComponent(source, scopeSeed, classify, seedClassify)
-    const { script, stateNames, derivedNames, computedNames, cellReadNames, nodes } = resolved
+    const { script, stateNames, derivedNames, computedNames, cellReadNames, blockingCellNames, nodes } =
+        resolved
     const build = generateBuild(
         nodes,
         'host',
@@ -38,6 +39,7 @@ export function compileComponent(
         computedNames,
         isLayout,
         cellReadNames,
+        blockingCellNames,
     )
     /* The scoped CSS is bundled into the entry stylesheet (see `abideUiPlugin`), not
        injected at runtime; the build only needs the `data-a-…` scope attributes on

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

@@ -66,6 +66,18 @@ export function compileSSR(
         flightDecls,
         hasStagedChildren,
     } = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout, cellReadNames)
+    /* ADR-0042 D7 (barrier completeness): every async cell — and so every BLOCKING (`await`) cell —
+       is declared in the lowered script (`lowered`), which the body below emits BEFORE the
+       `$$settleAsyncCells` barrier; the template back-end (`ssr`) constructs no cells. A blocking
+       cell built AFTER its barrier would ship an unresolved value the client then SUSPENDS against,
+       desyncing hydration. The invariant holds by construction today (cells are a script-block
+       construct); assert it as a tripwire so a future template lowering that emits a cell
+       construction fails the build LOUDLY here instead of as a runtime hydration desync. */
+    if (/\$\$scope\(\)\.(trackedComputed|computed|linked)\(/.test(ssr)) {
+        throw new Error(
+            '[abide] a reactive cell is constructed in template output, after the async-cell barrier (ADR-0042 D7) — cells must be declared in the component script so they settle before the SSR flush.',
+        )
+    }
     /* ADR-0039: a component with hoistable children declares `$childSlots` (the body walk reserves an
        output slot per child) and, after the walk, awaits `$$finalizeStreamedChildren` — which fills
        each slot inline (settled child, byte-identical to the old inline await) or with a streaming

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

@@ -1,6 +1,8 @@
 import ts from 'typescript'
 import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
 import { attrLiftPosition } from './attrLiftPosition.ts'
+import { hasTopLevelAwait } from './hasTopLevelAwait.ts'
+import { isFunctionScopeBoundary } from './isFunctionScopeBoundary.ts'
 import { isWhitespaceText } from './isWhitespaceText.ts'
 import { type LiftPosition, liftAsyncSubExpressions } from './liftAsyncSubExpressions.ts'
 import { parseTemplate } from './parseTemplate.ts'
@@ -102,6 +104,15 @@ export function compileShadow(
     builder.raw(
         'declare function $$cellValue<R>(seed: () => R): R extends AsyncIterable<infer F> ? F : Awaited<R>\n',
     )
+    /* The STREAMING sibling (ADR-0042): a no-`await` async `computed`/`linked` cell reads
+       `undefined`-while-pending, so its shadow type is the resolved value UNIONED with `undefined` —
+       the author must guard it (`?.`/`??`), exactly the runtime. A BLOCKING (`await`) cell uses
+       `$$cellValue` above (resolved `T`, never pending — its render region suspends). Selected in
+       `scopeLineFor` by the syntactic blocking bit. Unconditional (a named cell can occur with no
+       classifier), matching `$$cellValue`. */
+    builder.raw(
+        'declare function $$cellValuePending<R>(seed: () => R): (R extends AsyncIterable<infer F> ? F : Awaited<R>) | undefined\n',
+    )
     /* The peek helpers the async-interpolation wrap targets (ADR-0032): `$$peek` unwraps a promise
        sub-expression to its resolved value (`undefined` while pending) and `$$peekStream` reads an
        async iterable's latest frame, so `getFoo()?.name`/`{#if getFoo()}` type-check against the
@@ -712,7 +723,13 @@ function scopeLineFor(
     const fnIsThunk = ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)
     const wrapPrefix = fnIsThunk ? '' : seedIsAsync(fn) ? 'async () => (' : '() => ('
     const wrapSuffix = fnIsThunk ? '' : ')'
-    const prefix = `${keyword} ${name}${annotation} = $$cellValue(${wrapPrefix}`
+    /* ADR-0042: a STREAMING promise cell (async seed, no top-level `await`) reads
+       `undefined`-while-pending → `$$cellValuePending` (resolved `T | undefined`). A BLOCKING
+       (`await`) cell suspends its region so it is always resolved, and a sync cell is never pending
+       → `$$cellValue` (resolved `T`). (A bare stream seed keeps `$$cellValue`'s frame type — the
+       pre-existing type-directed case, unchanged here.) */
+    const helper = seedIsAsync(fn) && !seedIsBlocking(fn) ? '$$cellValuePending' : '$$cellValue'
+    const prefix = `${keyword} ${name}${annotation} = ${helper}(${wrapPrefix}`
     return withCalleeRef({
         text: `${prefix}${verbatim(fn)}${wrapSuffix});`,
         segments: [span(declaration.name, keywordOffset), span(fn, prefix.length)],
@@ -732,40 +749,20 @@ function seedIsAsync(seed: ts.Expression): boolean {
                 ?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ?? false
         )
     }
-    return expressionHasTopLevelAwait(seed)
+    return hasTopLevelAwait(seed)
 }
 
-/* True when `node` contains an `await` at its own top level — not nested inside a function. The
-   seed-classification counterpart to `collectTopLevelAwaitDiagnostics`' walk; kept local so the
-   shadow doesn't reach into `desugarSignals`' private `hasTopLevelAwait`. */
-function expressionHasTopLevelAwait(node: ts.Node): boolean {
-    let found = false
-    const visit = (child: ts.Node): void => {
-        if (found || isFunctionScopeBoundary(child)) {
-            return
-        }
-        if (ts.isAwaitExpression(child)) {
-            found = true
-            return
-        }
-        ts.forEachChild(child, visit)
+/* True for a BLOCKING async cell (ADR-0042 D6): an async thunk whose BODY has a top-level `await`
+   (`computed(async () => await X)`), or a bare seed carrying a top-level `await` (`computed(await
+   X)` — wrapSeed makes it an async thunk over that await). An async thunk with NO await
+   (`computed(async () => getFoo())`) is STREAMING, not blocking. Shares `hasTopLevelAwait` with
+   desugarSignals' `isBlockingSeed` so the shadow type (`$$cellValue` vs `$$cellValuePending`) agrees
+   with the runtime's blocking flag — the "one predicate" ADR-0042 D5 requires. */
+function seedIsBlocking(seed: ts.Expression): boolean {
+    if (ts.isArrowFunction(seed) || ts.isFunctionExpression(seed)) {
+        return seedIsAsync(seed) && hasTopLevelAwait(seed.body)
     }
-    visit(node)
-    return found
-}
-
-/* A node that opens its own (possibly async) function scope — awaits inside it are the author's
-   concern, so both the top-level-await walk and the seed classifier stop descending here. */
-function isFunctionScopeBoundary(node: ts.Node): boolean {
-    return (
-        ts.isFunctionDeclaration(node) ||
-        ts.isFunctionExpression(node) ||
-        ts.isArrowFunction(node) ||
-        ts.isMethodDeclaration(node) ||
-        ts.isGetAccessorDeclaration(node) ||
-        ts.isSetAccessorDeclaration(node) ||
-        ts.isConstructorDeclaration(node)
-    )
+    return hasTopLevelAwait(seed)
 }
 
 /* Whether any ELEMENT in the tree carries an `attach` — gates emitting the DOM-typed
@@ -1047,7 +1044,11 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                 } else if (branch.branch === 'catch' && branch.as !== undefined) {
                     builder.raw('const ')
                     builder.mapped(branch.as, branch.asLoc)
-                    builder.raw(' = undefined as any;\n')
+                    /* `unknown`, not `any` — a `catch` error is statically unknowable, and this
+                       matches what strict-mode plain TS gives a real `catch (err)`
+                       (`useUnknownInCatchVariables`), so the author must narrow before dereferencing
+                       (`err instanceof Error ? … : …`) exactly as outside a template (ADR-0042 fidelity). */
+                    builder.raw(' = undefined as unknown;\n')
                 }
                 emitNodes(branch.children, builder)
                 builder.raw('}\n')
@@ -1093,7 +1094,9 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                handlers consume their own branches inline and never route through this case. */
             builder.raw('{\n')
             if (node.as !== undefined) {
-                builder.raw(`const ${node.as} = undefined as any;\n`)
+                /* `unknown`, not `any` — see the await-`catch` binding above (matches strict TS's
+                   `catch (err)`, forcing the author to narrow). */
+                builder.raw(`const ${node.as} = undefined as unknown;\n`)
             }
             emitNodes(node.children, builder)
             builder.raw('}\n')

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

@@ -1,5 +1,6 @@
 import ts from 'typescript'
 import { assignmentTargetNames } from './assignmentTargetNames.ts'
+import { hasTopLevelAwait } from './hasTopLevelAwait.ts'
 import { type ReactiveImportBindings, reactiveImportBindings } from './resolveReactiveExport.ts'
 import { signalCallee } from './signalCallee.ts'
 import type { InterpolationKind } from './types/InterpolationKind.ts'
@@ -13,34 +14,6 @@ type EagerStreamPredicate = (declaration: ts.VariableDeclaration) => boolean
 
 const factory = ts.factory
 
-/* True when `node` holds an `await` that runs at the seed's own top level — one NOT nested
-   inside a further function. The walk stops at every nested function boundary, so an
-   `await` in an inner callback (`items.map(async (x) => await f(x))`) does not count: only
-   a top-level `await` marks the seed itself as an async thunk the async-cell path unwraps. */
-function hasTopLevelAwait(node: ts.Node): boolean {
-    let found = false
-    const visit = (child: ts.Node): void => {
-        if (found) {
-            return
-        }
-        /* A nested function is its own await scope — don't descend into it. */
-        if (
-            ts.isFunctionDeclaration(child) ||
-            ts.isFunctionExpression(child) ||
-            ts.isArrowFunction(child)
-        ) {
-            return
-        }
-        if (ts.isAwaitExpression(child)) {
-            found = true
-            return
-        }
-        ts.forEachChild(child, visit)
-    }
-    visit(node)
-    return found
-}
-
 /* Normalises a `computed`/`linked` argument into a seed THUNK: a literal `() => …` /
    `function` argument passes through unchanged (the author already wrote the thunk), any
    other expression is wrapped as `() => arg`. The wrapper arrow is made ASYNC when the
@@ -106,6 +79,23 @@ function isBareCallComputed(declaration: ts.VariableDeclaration): boolean {
     return ts.isCallExpression(argument) || ts.isIdentifier(argument)
 }
 
+/* True when a `computed`/`linked` seed is a BLOCKING async cell (ADR-0042 D6): its wrapped seed
+   is an async thunk whose BODY has a top-level `await` — `computed(await X)` (wrapSeed makes it
+   `async () => await X`) or `computed(async () => await X)`. An async thunk with NO await
+   (`computed(async () => getFoo())`) is STREAMING — `await` is the sole blocking marker. A
+   sync/stream seed is not blocking. The read of a blocking cell suspends its render region until
+   the value resolves; a streaming cell reads `undefined`-while-pending. Reuses `hasTopLevelAwait`
+   applied to the thunk BODY (not the arrow), so the walk descends exactly one function level. */
+function isBlockingSeed(argument: ts.Expression): boolean {
+    const wrapped = wrapSeed(argument)
+    if (!isAsyncSeed(wrapped)) {
+        return false
+    }
+    const body =
+        ts.isArrowFunction(wrapped) || ts.isFunctionExpression(wrapped) ? wrapped.body : wrapped
+    return hasTopLevelAwait(body)
+}
+
 /* Emits a compile WARNING (best-effort, never fatal) when a signal read appears AFTER the
    first top-level `await` in an async seed — a value read there is no longer tracked, so the
    cell won't reseed when it changes. Detection only: reads before the await (or with no
@@ -223,6 +213,10 @@ export function desugarSignals(
     derivedNames: Set<string>
     computedNames: Set<string>
     cellReadNames: Set<string>
+    /* The full BLOCKING cell set (ADR-0042): the template-injected `await` cells passed in, unioned
+       with the script-level `await` computeds/linked collected here. The client template lowering
+       reads these via `$$readCellBlocking` (suspend-on-pending). */
+    blockingCellNames: Set<string>
 } {
     assertNoRemovedReaders(source)
     /* The full set of names written anywhere (this script + the template). A prop in this set
@@ -241,6 +235,10 @@ export function desugarSignals(
        One read shape covers both — `$$readCell` peeks an async cell and reads `.value` off a
        sync one — so `linked(getStream())` auto-tracks with no read-site branching. */
     const cellReadNames = new Set<string>()
+    /* Script-level BLOCKING cell names (ADR-0042 D6): a `computed`/`linked` whose seed carries a
+       top-level `await`. Unioned with the template-injected `blockingCellNames` and returned so the
+       CLIENT template lowering reads them via `$$readCellBlocking` (suspend-on-pending). */
+    const scriptBlockingNames = new Set<string>()
     /* A `props()` destructure must be lowered even when it declares no reactive binding
        (a rest-only `const { ...rest } = props()`), so track its presence on its own. */
     let hasPropsDestructure = false
@@ -325,6 +323,11 @@ export function desugarSignals(
                    or its seed type resolves to a stream (`isEagerStreamComputed`, ADR-0023). */
                 if (isAsyncComputed(declaration) || isEagerStreamComputed(declaration)) {
                     cellReadNames.add(declaration.name.text)
+                    /* A blocking async computed (author `await`) reads suspend-on-pending. */
+                    const argument = seedArgument(declaration)
+                    if (argument !== undefined && isBlockingSeed(argument)) {
+                        scriptBlockingNames.add(declaration.name.text)
+                    }
                 } else {
                     computedNames.add(declaration.name.text)
                 }
@@ -333,6 +336,11 @@ export function desugarSignals(
                    is synchronous, an `AsyncState` when it tracks a promise/stream — one read
                    shape auto-tracks whichever source the runtime primitive resolved to. */
                 cellReadNames.add(declaration.name.text)
+                /* A blocking async linked (author `await`) reads suspend-on-pending, like computed. */
+                const argument = seedArgument(declaration)
+                if (argument !== undefined && isBlockingSeed(argument)) {
+                    scriptBlockingNames.add(declaration.name.text)
+                }
             } else if (callee === 'state') {
                 /* `state(initial, transform)` → a `.value` cell (its write-coercion transform
                    forces a local store); referenced as `name.value`, unchanged. */
@@ -387,7 +395,14 @@ export function desugarSignals(
         return factory.updateSourceFile(root, statements)
     }
 
-    return { transformer, stateNames, derivedNames, computedNames, cellReadNames }
+    return {
+        transformer,
+        stateNames,
+        derivedNames,
+        computedNames,
+        cellReadNames,
+        blockingCellNames: new Set([...blockingCellNames, ...scriptBlockingNames]),
+    }
 }
 
 /* The lowered form of a top-level statement: state slots → `model.x = init`
@@ -627,10 +642,23 @@ function computedStatements(
                   )
                 : wrapSeed(argument)
         if (isAsyncSeed(wrapped)) {
-            /* Async seed → the eager `computed` primitive (an `AsyncComputed` cell, read via
-               `$$readCell`); the runtime unwraps the promise. */
+            /* Async seed → the eager async cell (`AsyncComputed`, read via `$$readCell`), the
+               runtime unwraps the promise. `await` in the thunk body → BLOCKING (joins the SSR
+               barrier, resolves inline, client suspends its render region); async modifier with NO
+               await → STREAMING (ships pending, resolves on the client) — ADR-0042 D6. Routed
+               through `trackedComputed(thunk, streaming)` (same createAsyncCell for an async thunk)
+               to carry the flag, matching the template-injected path. */
             warnPostAwaitReads(wrapped, signalNames)
-            statements.push(constDeclaration(name, scopeMethodCall('computed', [wrapped])))
+            const streaming = argument === undefined || !isBlockingSeed(argument)
+            statements.push(
+                constDeclaration(
+                    name,
+                    scopeMethodCall('trackedComputed', [
+                        wrapped,
+                        streaming ? factory.createTrue() : factory.createFalse(),
+                    ]),
+                ),
+            )
         } else if (isEagerStreamComputed(declaration)) {
             /* Stream seed → the eager `trackedComputed`, which probes the seed and auto-tracks a
                stream (`AsyncComputed`) or falls back to a lazy computed; read via `$$readCell`.

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

@@ -77,6 +77,10 @@ export function generateBuild(
     isLayout = false,
     /* `linked` / async `computed` names, lowered to `$$readCell(name)` in template exprs. */
     cellReadNames: ReadonlySet<string> = new Set(),
+    /* The subset that are BLOCKING `await` cells (ADR-0042), lowered to `$$readCellBlocking(name)`
+       on the CLIENT so a pending read suspends its render region. Server keeps `$$readCell` (the
+       SSR barrier resolves blocking cells before the template, so the read never suspends). */
+    blockingCellNames: ReadonlySet<string> = new Set(),
 ): string {
     const nextVar = makeVarNamer()
     /* A per-body source-order ordinal for each `<Child/>` mount site, so two same-type siblings
@@ -121,7 +125,7 @@ export function generateBuild(
         withShadow,
         bindRead,
         bindWrite,
-    } = lowerContext(stateNames, derivedNames, computedNames, cellReadNames)
+    } = lowerContext(stateNames, derivedNames, computedNames, cellReadNames, blockingCellNames)
 
     /* Maps a plan `Binding`'s classification to the client `ShadowKind`: a `reactive` value
        derefs as a `.value` cell (`derived`), a `plain` value as the bare local (`plain`). The

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

@@ -0,0 +1,28 @@
+import ts from 'typescript'
+import { isFunctionScopeBoundary } from './isFunctionScopeBoundary.ts'
+
+/*
+True when `node` contains an `await` at its OWN top level — not nested inside any function scope
+(`isFunctionScopeBoundary`: function/arrow/method/accessor/constructor). The SINGLE seed classifier
+both the build lowering (`desugarSignals`: `await` present → a BLOCKING cell that suspends its render
+region) and the type shadow (`compileShadow`: `$$cellValue` `T` vs `$$cellValuePending` `T | undefined`)
+share, so the runtime blocking flag and the shadow type can never disagree on whether a seed is
+`await`-marked (ADR-0042 D5's "one predicate"). An `await` in an inner callback / method
+(`items.map(async (x) => await f(x))`, `{ async m() { await x } }`) does NOT count — only a
+top-level `await` marks the seed itself.
+*/
+export function hasTopLevelAwait(node: ts.Node): boolean {
+    let found = false
+    const visit = (child: ts.Node): void => {
+        if (found || isFunctionScopeBoundary(child)) {
+            return
+        }
+        if (ts.isAwaitExpression(child)) {
+            found = true
+            return
+        }
+        ts.forEachChild(child, visit)
+    }
+    visit(node)
+    return found
+}

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

@@ -0,0 +1,20 @@
+import ts from 'typescript'
+
+/*
+A node that opens its own (possibly async) function scope — awaits inside it are that scope's
+concern, not the enclosing seed's. Both the top-level-await walk (`hasTopLevelAwait`) and the
+top-level-await diagnostics stop descending here, so a seed classifies the same way a value read
+inside such a scope would behave. One predicate shared by the build lowering and the type shadow so
+they can never disagree on a boundary (ADR-0042 D5's "one predicate").
+*/
+export function isFunctionScopeBoundary(node: ts.Node): boolean {
+    return (
+        ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node) ||
+        ts.isConstructorDeclaration(node)
+    )
+}

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

@@ -101,8 +101,8 @@ export function liftAsyncSubExpressions(
         /* A nested function is its own evaluation scope — an async (sub)expression inside a callback
            (`items.map(x => fetchName(x))`, `items.map(async x => await load(x))`) must NOT be hoisted
            to a top-level cell: its parameters/closure vars would become free identifiers, and it
-           would run once instead of per row. Stop at the boundary, mirroring
-           `desugarSignals.hasTopLevelAwait`. */
+           would run once instead of per row. Stop at the boundary, mirroring the shared
+           `hasTopLevelAwait` walk. */
         if (
             ts.isArrowFunction(node) ||
             ts.isFunctionExpression(node) ||

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

@@ -27,6 +27,9 @@ export function lowerContext(
     computedNames: ReadonlySet<string> = new Set(),
     /* `linked` / async `computed` names, read through `$$readCell(name)`. */
     cellReadNames: ReadonlySet<string> = new Set(),
+    /* The subset that are BLOCKING `await` cells (ADR-0042), read through `$$readCellBlocking(name)`
+       (suspend-on-pending). Passed only by the CLIENT back-end; SSR leaves it empty. */
+    blockingCellNames: ReadonlySet<string> = new Set(),
 ) {
     /* The typed branch-local shadow stack: one auto-popping value owning both kinds.
        `derived` names deref to `.value` like a `computed` (block value params the client
@@ -51,6 +54,7 @@ export function lowerContext(
                 new Set(scope.names('derived')),
                 new Set(scope.names('plain')),
                 cellReadNames,
+                blockingCellNames,
             ),
             docAccessTransformer('$$model'),
         ])

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,
     }
 }