@abide/abide 0.51.0 → 0.53.0

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

@@ -0,0 +1,19 @@
+import ts from 'typescript'
+
+/*
+Maps a compound-assignment operator to its plain binary counterpart, for lowering
+`x += y` into an unconditional read-combine-write. Logical assignments
+(`||=`/`&&=`/`??=`) lower the same way — the patch/cell write always fires,
+consistent with how `+=` lowers. Shared by lowerDocAccess (the `$$model` write path)
+and renameSignalRefs (the `$$writeCell` linked-cell path) so the two lowerings can't
+drift.
+*/
+export const COMPOUND_ASSIGNMENT_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
+    [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.PlusToken],
+    [ts.SyntaxKind.MinusEqualsToken, ts.SyntaxKind.MinusToken],
+    [ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskToken],
+    [ts.SyntaxKind.SlashEqualsToken, ts.SyntaxKind.SlashToken],
+    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
+    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
+    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
+])

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

@@ -56,6 +56,8 @@ 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' },
     { name: 'settleAsyncCells', specifier: 'ui/settleAsyncCells', alias: '$$settleAsyncCells' },

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'
@@ -94,6 +96,23 @@ export function compileShadow(
         watchLocalName,
     } = analyzeScript(scriptBody, scriptStart)
     builder.raw(shadowPreamble(importedReactives))
+    /* Every `computed`/`linked` scope line reads through this: it invokes the seed thunk and
+       unwraps a promise/stream to the value a BARE cell read peeks (ADR-0019/0032) — so an async
+       `computed(await …)` / stream `computed(src)` type-checks as its resolved value, and a sync
+       seed keeps its return type (`Awaited` is identity on a non-thenable). Reserved `$$` name so
+       it can never collide with an author binding; `declare`-only, so it carries no runtime. */
+    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
@@ -395,27 +414,38 @@ function collectReservedNameDiagnostics(
    top-level await transpiles to `await` in a non-async function and breaks the bundle; the
    shadow's render fn is async, so `tsc` alone never flags it (a check/runtime parity gap).
    Stops descending at function boundaries — their own async-ness is the author's concern —
-   and catches both `await expr` and `for await (… of …)`, flagging the `await` keyword. */
+   and catches both `await expr` and `for await (… of …)`, flagging the `await` keyword. A
+   `computed`/`linked` SEED argument is exempt: `wrapSeed` (desugarSignals) lowers a top-level
+   `await` there into an async thunk (`computed(await load())` → `async () => await load()`), so
+   its await runs off the sync build — flagging it would be a false positive. */
 function collectTopLevelAwaitDiagnostics(
     file: ts.SourceFile,
     scriptStart: number,
     diagnostics: ShadowDiagnostic[],
+    bindings: ReactiveImportBindings,
 ): void {
     const message =
         'top-level `await` is not allowed in a `<script>` — the component build runs synchronously. Use `{#await expr}…{:then value}…{/await}` markup for blocking data, or `await` inside an async event handler.'
     const visit = (node: ts.Node): void => {
         /* A nested function introduces its own (possibly async) scope; its awaits are legal. */
-        if (
-            ts.isFunctionDeclaration(node) ||
-            ts.isFunctionExpression(node) ||
-            ts.isArrowFunction(node) ||
-            ts.isMethodDeclaration(node) ||
-            ts.isGetAccessorDeclaration(node) ||
-            ts.isSetAccessorDeclaration(node) ||
-            ts.isConstructorDeclaration(node)
-        ) {
+        if (isFunctionScopeBoundary(node)) {
             return
         }
+        /* A `computed`/`linked` seed becomes an async thunk (`wrapSeed`), so an await in it is
+           legal — visit the callee and any trailing args, but skip the seed (`arguments[0]`). */
+        if (ts.isCallExpression(node) && node.arguments.length > 0) {
+            const callee = resolveReactiveExport(node.expression, bindings)
+            if (callee === 'computed' || callee === 'linked') {
+                visit(node.expression)
+                for (let index = 1; index < node.arguments.length; index++) {
+                    const argument = node.arguments[index]
+                    if (argument !== undefined) {
+                        visit(argument)
+                    }
+                }
+                return
+            }
+        }
         /* The `await` keyword token: the AwaitExpression's first child, or a `for await`'s
            await modifier. */
         const keyword = ts.isAwaitExpression(node)
@@ -449,7 +479,8 @@ function collectNestedScriptAwaitDiagnostics(
         }
         if (node.kind === 'script' && node.loc !== undefined) {
             const file = ts.createSourceFile('nested.ts', node.code, ts.ScriptTarget.Latest, true)
-            collectTopLevelAwaitDiagnostics(file, node.loc, diagnostics)
+            /* A nested script inherits the surface by canonical name (no imports of its own). */
+            collectTopLevelAwaitDiagnostics(file, node.loc, diagnostics, NESTED_REACTIVE_BINDINGS)
         }
         if ('children' in node) {
             collectNestedScriptAwaitDiagnostics(node.children, diagnostics)
@@ -503,7 +534,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     collectReservedNameDiagnostics(file, scriptStart, diagnostics)
     /* The leading script runs in the synchronous `build()`, so a top-level await breaks the
        bundle — catch it here with a legible message instead of an opaque transpile error. */
-    collectTopLevelAwaitDiagnostics(file, scriptStart, diagnostics)
+    collectTopLevelAwaitDiagnostics(file, scriptStart, diagnostics, bindings)
     /* A verbatim span: original text + the segment mapping it back, relative to the
        line start (the caller rebases shadowStart onto the running shadow length). */
     const span = (node: ts.Node, prefixLength: number): ScopeLine['segments'][number] => ({
@@ -683,13 +714,57 @@ function scopeLineFor(
             segments: [span(declaration.name, keywordOffset)],
         })
     }
-    const prefix = `${keyword} ${name}${annotation} = (`
+    /* Mirror `wrapSeed` (desugarSignals): a bare (non-thunk) seed is normalised to `() => (seed)`,
+       made ASYNC when it carries a top-level `await` — so `computed(await load())` projects as a
+       legal async thunk instead of a raw top-level await (`(await load())()` — a build-breaker that
+       also mis-called the resolved value). A literal thunk passes through unchanged. `$$cellValue`
+       then invokes it and unwraps a promise/stream to the value a bare read peeks, so an async or
+       stream seed types as its RESOLVED value (`Promise<T>` → `T`) rather than the raw promise. */
+    const fnIsThunk = ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)
+    const wrapPrefix = fnIsThunk ? '' : seedIsAsync(fn) ? 'async () => (' : '() => ('
+    const wrapSuffix = fnIsThunk ? '' : ')'
+    /* 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)})();`,
+        text: `${prefix}${verbatim(fn)}${wrapSuffix});`,
         segments: [span(declaration.name, keywordOffset), span(fn, prefix.length)],
     })
 }
 
+/* True for a `computed`/`linked` seed that `wrapSeed` (desugarSignals) turns into an ASYNC thunk —
+   a thunk the author wrote `async`, or a bare seed carrying a top-level `await` (`computed(await
+   x)`). The shadow must agree so it unwraps the promise to the resolved value AND so the top-level
+   await scan spares the seed. Stops at function boundaries — an inner `async` callback is its own
+   scope, mirroring `hasTopLevelAwait`. */
+function seedIsAsync(seed: ts.Expression): boolean {
+    if (ts.isArrowFunction(seed) || ts.isFunctionExpression(seed)) {
+        return (
+            ts
+                .getModifiers(seed)
+                ?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ?? false
+        )
+    }
+    return hasTopLevelAwait(seed)
+}
+
+/* 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)
+    }
+    return hasTopLevelAwait(seed)
+}
+
 /* Whether any ELEMENT in the tree carries an `attach` — gates emitting the DOM-typed
    attachment aliases. All nested content (block bodies, await/switch branches, snippet
    bodies) routes through `children`, so a recursive `children` walk is complete. */
@@ -969,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')
@@ -1015,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/lowerDocAccess.ts

@@ -1,5 +1,6 @@
 import ts from 'typescript'
 import { escapeKey } from '../runtime/escapeKey.ts'
+import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
 
 /*
 The linchpin compiler pass. Rewrites idiomatic data access on a reactive document
@@ -30,9 +31,6 @@ used as an index lowers too. Exposed as `docAccessTransformer` (a
 /* A path segment is either a literal key or a runtime expression (a dynamic index). */
 type Segment = { kind: 'literal'; value: string } | { kind: 'expression'; node: ts.Expression }
 
-/* Maps a compound-assignment operator to its plain binary counterpart. Logical
-   assignments (`||=`/`&&=`/`??=`) lower to an unconditional replace of the
-   combined value — consistent with how `+=` lowers (the patch always writes). */
 /* Methods that mutate a doc-rooted container in place — Array, Map and Set (the three
    mutable containers the doc codec serializes). Called on a doc value these can't lower to
    a bare `readCall` (which would mutate the live tree by reference and never emit a patch —
@@ -57,16 +55,6 @@ const MUTATING_CONTAINER_METHODS = new Set([
     'clear',
 ])
 
-const COMPOUND_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
-    [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.PlusToken],
-    [ts.SyntaxKind.MinusEqualsToken, ts.SyntaxKind.MinusToken],
-    [ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskToken],
-    [ts.SyntaxKind.SlashEqualsToken, ts.SyntaxKind.SlashToken],
-    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
-    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
-    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
-])
-
 export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.SourceFile> {
     return (context) => (root) => {
         /* Collects the path of an access chain rooted at `docName`, visiting any
@@ -114,7 +102,7 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
                             ts.visitNode(node.right, visit) as ts.Expression,
                         ])
                     }
-                    const binary = COMPOUND_OPERATORS.get(operator)
+                    const binary = COMPOUND_ASSIGNMENT_OPERATORS.get(operator)
                     if (binary) {
                         const next = ts.factory.createBinaryExpression(
                             docCall(docName, 'read', [buildPath(segments)]),

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,
@@ -117,9 +126,14 @@ export function lowerScript(
         ...computedNames,
         ...cellReadNames,
     ])
+    /* `wrapReactionCellSources` only folds `watch(cell, …)` calls, so it's a pure
+       identity walk when the script imports no `watch` (the common case) — skip the
+       extra full-tree pass entirely then. */
+    const reactionTransforms =
+        watchLocalNames.size > 0 ? [wrapReactionCellSources(cellNames, watchLocalNames)] : []
     const result = ts.transform(source, [
         transformer,
-        wrapReactionCellSources(cellNames, watchLocalNames),
+        ...reactionTransforms,
         signalRefsTransformer(
             stateNames,
             derivedNames,
@@ -180,6 +194,7 @@ export function lowerScript(
         derivedNames,
         computedNames,
         cellReadNames,
+        blockingCellNames: allBlockingNames,
         droppedReactiveImports,
     }
 }