@abide/abide 0.52.0 → 0.54.0

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
@@ -63,6 +36,24 @@ function wrapSeed(argument: ts.Expression): ts.Expression {
     )
 }
 
+/* Wraps a seed expression as an async unwrapping thunk `async () => await (arg)` — for a
+   type-directed PROMISE seed (ADR-0023/0043) the author wrote WITHOUT `await`
+   (`state.computed(getFoo())`). The `async`+`await` makes createAsyncCell unwrap the resolved
+   value; a plain `() => getFoo()` thunk would fall to trackedComputed's lazy opaque path (its
+   probe self-identifies only a stream, never a promise). The parens keep a comma/ternary seed
+   a single await operand. Distinct from `wrapSeed`, which only makes the arrow async when the
+   arg already carries a top-level `await`. */
+function wrapAwaitSeed(argument: ts.Expression): ts.Expression {
+    return factory.createArrowFunction(
+        [factory.createModifier(ts.SyntaxKind.AsyncKeyword)],
+        undefined,
+        [],
+        undefined,
+        factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+        factory.createAwaitExpression(factory.createParenthesizedExpression(argument)),
+    )
+}
+
 /* True for an async seed thunk — an arrow/function carrying the `async` modifier, whether
    from `wrapSeed`'s `await` lowering or a passthrough `async () => …` literal the author
    wrote. The routing signal: an async seed becomes an async cell (read via `$$readCell`),
@@ -106,6 +97,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 +231,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 +253,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
@@ -277,6 +293,21 @@ export function desugarSignals(
         }
         return isBareCallComputed(declaration)
     }
+    /* A type-directed PROMISE seed (ADR-0023/0043): a no-`await` `state.computed(getFoo())` whose
+       seed's checker type resolves to a promise. Routed to an eager STREAMING async cell that
+       unwraps the resolved value and reactively re-resolves when its tracked deps change — the
+       script-level twin of a bare async interpolation (ADR-0032). Only fires with a warm classifier
+       ('promise'); fail-open (no program) leaves it to `isEagerStreamComputed`'s bare-call probe,
+       and the `await`-marker seed is excluded (its wrapped thunk is already async). Kept separate
+       from `isEagerStreamComputed` so `computedStatements` can wrap it as `async () => await (seed)`
+       (a stream seed stays a bare probe thunk). */
+    const isPromiseComputed: EagerStreamPredicate = (declaration) => {
+        const argument = seedArgument(declaration)
+        if (argument === undefined || isAsyncSeed(wrapSeed(argument))) {
+            return false
+        }
+        return seedKind(argument) === 'promise'
+    }
     for (const statement of source.statements) {
         if (!ts.isVariableStatement(statement)) {
             continue
@@ -323,8 +354,19 @@ export function desugarSignals(
                    `name()` (a sync/promise seed), or an eager cell read via `$$readCell(name)`
                    when the wrapped seed is async (an `await`-lowered / passthrough-`async` thunk)
                    or its seed type resolves to a stream (`isEagerStreamComputed`, ADR-0023). */
-                if (isAsyncComputed(declaration) || isEagerStreamComputed(declaration)) {
+                if (
+                    isAsyncComputed(declaration) ||
+                    isEagerStreamComputed(declaration) ||
+                    isPromiseComputed(declaration)
+                ) {
                     cellReadNames.add(declaration.name.text)
+                    /* A blocking async computed (author `await`) reads suspend-on-pending; a bare
+                       promise (isPromiseComputed) carries no `await` → streaming, so isBlockingSeed
+                       is false and it never joins this set. */
+                    const argument = seedArgument(declaration)
+                    if (argument !== undefined && isBlockingSeed(argument)) {
+                        scriptBlockingNames.add(declaration.name.text)
+                    }
                 } else {
                     computedNames.add(declaration.name.text)
                 }
@@ -333,6 +375,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. */
@@ -381,13 +428,21 @@ export function desugarSignals(
                     blockingCellNames,
                     writtenNames,
                     isEagerStreamComputed,
+                    isPromiseComputed,
                 ),
             )
         }
         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`
@@ -402,12 +457,19 @@ function loweredStatement(
     blockingCellNames: ReadonlySet<string>,
     writtenNames: ReadonlySet<string>,
     isEagerStreamComputed: EagerStreamPredicate,
+    isPromiseComputed: EagerStreamPredicate,
 ): ts.Statement[] {
     rejectMixedDeclaration(statement, bindings)
     return (
         injectedComputedStatements(statement, injectedCellNames, blockingCellNames) ??
         stateAssignmentStatements(statement, bindings) ??
-        computedStatements(statement, bindings, signalNames, isEagerStreamComputed) ??
+        computedStatements(
+            statement,
+            bindings,
+            signalNames,
+            isEagerStreamComputed,
+            isPromiseComputed,
+        ) ??
         propsStatements(statement, bindings, writtenNames) ??
         cellStatements(statement, bindings, signalNames) ?? [statement]
     )
@@ -598,6 +660,7 @@ function computedStatements(
     bindings: ReactiveImportBindings,
     signalNames: ReadonlySet<string>,
     isEagerStreamComputed: EagerStreamPredicate,
+    isPromiseComputed: EagerStreamPredicate,
 ): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
@@ -627,10 +690,40 @@ 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 (argument !== undefined && isPromiseComputed(declaration)) {
+            /* Type-directed PROMISE seed (ADR-0023/0043): a bare `state.computed(getFoo())` whose
+               seed resolves to a promise. Wrap it as `async () => await (seed)` so createAsyncCell
+               unwraps the resolved value — a plain `() => getFoo()` thunk would fall to
+               trackedComputed's lazy opaque path (its probe self-identifies only a stream). Passed
+               `streaming: true` (the `true` arg): no author `await` → it does NOT join the SSR
+               blocking barrier — the shell ships pending and the client resolves + reactively
+               re-resolves, the ADR-0032 no-await tier. `await getFoo()` stays the BLOCKING form. */
+            statements.push(
+                constDeclaration(
+                    name,
+                    scopeMethodCall('trackedComputed', [
+                        wrapAwaitSeed(argument),
+                        factory.createTrue(),
+                    ]),
+                ),
+            )
         } 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/interpolationClassifierForRoot.ts

@@ -1,4 +1,5 @@
-import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+import { cachedShadowProgram } from './cachedShadowProgram.ts'
+import type { ShadowProgram } from './createShadowProgram.ts'
 import { shadowInterpolationClassifier } from './shadowInterpolationClassifier.ts'
 import type { InterpolationClassifier } from './types/InterpolationClassifier.ts'
 
@@ -12,24 +13,18 @@ The incremental `createShadowLanguageService` does not expose the checker, shado
 `ts.SourceFile`, or per-file mappings publicly, so v1 uses the one-shot
 `createShadowProgram` (reused per root) rather than the LS overlay path.
 
-FAIL-OPEN throughout: if the program can't be built, or the file has no shadow, the
-classifier is absent (→ today's plain-value binding); and the returned closure wraps
-its whole body so ANY throw (resolution failure, missing node, checker hiccup) returns
-`'sync'`. A type-resolution problem degrades to today's behavior, never breaks the build.
+FAIL-OPEN throughout: if the program can't be built (warned once per root by
+`cachedShadowProgram`), or the file has no shadow, the classifier is absent (→ today's
+plain-value binding); and the returned closure wraps its whole body so ANY throw
+(resolution failure, missing node, checker hiccup) returns `'sync'`. A type-resolution
+problem degrades to today's behavior, never breaks the build.
 */
 export function interpolationClassifierForRoot(
     cache: Map<string, ShadowProgram | undefined>,
     root: string,
     abidePath: string,
 ): InterpolationClassifier | undefined {
-    if (!cache.has(root)) {
-        try {
-            cache.set(root, createShadowProgram(root))
-        } catch {
-            cache.set(root, undefined)
-        }
-    }
-    const shadowProgram = cache.get(root)
+    const shadowProgram = cachedShadowProgram(cache, root)
     if (shadowProgram === undefined) {
         return undefined
     }

package/src/lib/ui/compile/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/lowerCompoundAssignment.ts

@@ -0,0 +1,49 @@
+import ts from 'typescript'
+
+/* Arithmetic compound assignments → their plain binary counterpart, lowered to a
+   read-combine-write (`x += y` → `write(read + y)`). */
+const ARITHMETIC_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],
+])
+
+/* Logical compound assignments SHORT-CIRCUIT: the write fires only when the guard
+   passes (`x ??= v` is `x ?? (x = v)`), so they lower to `read <op> write(right)`, NOT
+   an unconditional write — matching JS, so a non-nullish/truthy/falsy guard does no
+   needless patch or cell reseed. */
+const LOGICAL_ASSIGNMENT_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
+    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
+    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
+    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
+])
+
+/*
+Lowers an assignment (`=`, arithmetic `+=`, or logical `??=`/`||=`/`&&=`) to a reactive
+write, shared by the `$$model` doc path (lowerDocAccess) and the `$$writeCell` linked-cell
+path (renameSignalRefs) so the two lowerings can't drift. `makeRead` builds the target's
+read expression (only called for compound operators); `makeWrite` wraps a value in the
+write call. Returns undefined for an operator this doesn't handle so the caller can leave
+the node untouched. The write must evaluate to the written value (see `Cell.set` /
+`Doc.replace`) for the logical short-circuit to yield the right result.
+*/
+export function lowerCompoundAssignment(
+    operator: ts.SyntaxKind,
+    makeRead: () => ts.Expression,
+    right: ts.Expression,
+    makeWrite: (value: ts.Expression) => ts.Expression,
+): ts.Expression | undefined {
+    if (operator === ts.SyntaxKind.EqualsToken) {
+        return makeWrite(right)
+    }
+    const arithmetic = ARITHMETIC_COMPOUND_OPERATORS.get(operator)
+    if (arithmetic !== undefined) {
+        return makeWrite(ts.factory.createBinaryExpression(makeRead(), arithmetic, right))
+    }
+    const logical = LOGICAL_ASSIGNMENT_OPERATORS.get(operator)
+    if (logical !== undefined) {
+        return ts.factory.createBinaryExpression(makeRead(), logical, makeWrite(right))
+    }
+    return undefined
+}

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,6 +1,7 @@
 import ts from 'typescript'
 import { escapeKey } from '../runtime/escapeKey.ts'
-import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
+import { lowerCompoundAssignment } from './lowerCompoundAssignment.ts'
+import { lowerUpdateExpression } from './lowerUpdateExpression.ts'
 
 /*
 The linchpin compiler pass. Rewrites idiomatic data access on a reactive document
@@ -91,33 +92,24 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
         }
 
         function visit(node: ts.Node): ts.Node {
-            /* Assignment (plain or compound) to a doc path → replace patch. */
+            /* Assignment (plain, compound, or logical) to a doc path → replace patch. */
             if (ts.isBinaryExpression(node)) {
                 const segments = pathSegments(node.left as ts.Expression)
                 if (segments) {
-                    const operator = node.operatorToken.kind
-                    if (operator === ts.SyntaxKind.EqualsToken) {
-                        return docCall(docName, 'replace', [
-                            buildPath(segments),
-                            ts.visitNode(node.right, visit) as ts.Expression,
-                        ])
-                    }
-                    const binary = COMPOUND_ASSIGNMENT_OPERATORS.get(operator)
-                    if (binary) {
-                        const next = ts.factory.createBinaryExpression(
-                            docCall(docName, 'read', [buildPath(segments)]),
-                            binary,
-                            ts.visitNode(node.right, visit) as ts.Expression,
-                        )
-                        return docCall(docName, 'replace', [buildPath(segments), next])
+                    const lowered = lowerCompoundAssignment(
+                        node.operatorToken.kind,
+                        () => docCall(docName, 'read', [buildPath(segments)]),
+                        ts.visitNode(node.right, visit) as ts.Expression,
+                        (value) => docCall(docName, 'replace', [buildPath(segments), value]),
+                    )
+                    if (lowered !== undefined) {
+                        return lowered
                     }
                 }
             }
-            /* `path++` / `++path` / `path--` on a doc path → a replace patch (the same
-               shape as `+= 1`). A bare `++` would otherwise survive onto the lowered read
-               (`model.read("n")++` / `cell.get()++`) — invalid, since a call result is not
-               an lvalue. abide handlers are statements, so the postfix/prefix value is
-               discarded and both lower identically. Only `++`/`--` are handled here; other
+            /* `path++` / `++path` / `path--` on a doc path → a replace patch. A bare `++`
+               would otherwise survive onto the lowered read (`model.read("n")++`) — invalid,
+               since a call result is not an lvalue. Only `++`/`--` are handled here; other
                unary operators (`!path`, `-path`) fall through so their operand lowers as a
                normal read. */
             if (
@@ -127,16 +119,12 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
             ) {
                 const segments = pathSegments(node.operand)
                 if (segments) {
-                    const step =
-                        node.operator === ts.SyntaxKind.PlusPlusToken
-                            ? ts.SyntaxKind.PlusToken
-                            : ts.SyntaxKind.MinusToken
-                    const next = ts.factory.createBinaryExpression(
-                        docCall(docName, 'read', [buildPath(segments)]),
-                        step,
-                        ts.factory.createNumericLiteral(1),
+                    return lowerUpdateExpression(
+                        ts.isPostfixUnaryExpression(node),
+                        node.operator === ts.SyntaxKind.PlusPlusToken,
+                        () => docCall(docName, 'read', [buildPath(segments)]),
+                        (value) => docCall(docName, 'replace', [buildPath(segments), value]),
                     )
-                    return docCall(docName, 'replace', [buildPath(segments), next])
                 }
             }
             /* doc array `.push(a, b, …)` → one `add` patch per argument at the array's `-`