@abide/abide 0.53.0 → 0.55.0

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

@@ -4,12 +4,13 @@ import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
 import { ANCHOR } from '../runtime/RANGE_MARKER.ts'
 import { asOutlet } from './asOutlet.ts'
 import { awaitPlan } from './awaitPlan.ts'
+import { awaitSubjectExpr } from './awaitSubjectExpr.ts'
 import { bindListenEvent } from './bindListenEvent.ts'
+import { componentOrdinals } from './componentOrdinals.ts'
 import { composeProps } from './composeProps.ts'
 import { eachPlan } from './eachPlan.ts'
 import { elementPlan } from './elementPlan.ts'
 import { groupBindParts } from './groupBindParts.ts'
-import { hoistableChildRenders } from './hoistableChildRenders.ts'
 import { ifPlan } from './ifPlan.ts'
 import { interpolatedTemplateLiteral } from './interpolatedTemplateLiteral.ts'
 import { isControlFlow } from './isControlFlow.ts'
@@ -75,23 +76,12 @@ export function generateBuild(
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string>,
     isLayout = false,
-    /* `linked` / async `computed` names, lowered to `$$readCell(name)` in template exprs. */
+    /* `linked` / async `computed` names, lowered to `$$readCell(name)` in template exprs — one
+       read form whose pause-vs-peek (a blocking `await` cell suspends the region; a streaming
+       cell peeks `undefined`) is decided at runtime by the cell's own `blocking` bit (ADR-0042). */
     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
-       get distinct render-path segments. Combined with the ambient branch/row path a control-flow
-       ancestor pushes, this makes every mounted instance's id unique and stable (ADR render-path
-       identity). Drawn in document-order walk, matching the SSR back-end's identical walk. */
-    let childOrdinal = 0
-    /* ADR-0039: the SAME hoistable-child set the SSR back-end computes (identical inputs → identical
-       node identities), so the client emits the dual-mode `$$mountStreamedChild` for exactly the
-       children the server may stream. A non-hoistable child keeps the plain `$$mountChild`. */
-    const streamCapable = hoistableChildRenders(nodes, cellReadNames)
 
     /* In a layout, `<slot/>` outlets are rewritten to `OUTLET_TAG` elements up front
        (`asOutlet`) so the static-clone path carries them as ordinary structure. `asOutlet`
@@ -105,6 +95,12 @@ export function generateBuild(
        position structurally (the drift the shared context exists to prevent). */
     const { markText, elIndex, anIndex } = skeletonContext(rootNodes)
 
+    /* Each `<Child/>` mount site's render-path ordinal, from the ONE shared document-order
+       walk the SSR back-end also reads (`componentOrdinals`) — so two same-type siblings get
+       distinct, SSR-congruent segments regardless of either back-end's emission order. The
+       returned lookup throws on a miss (a structural divergence from the shared walk). */
+    const childOrdinal = componentOrdinals(rootNodes)
+
     /* The hole's index, assigned by the shared skeletonContext walk — the sole numberer. A
        missing entry means this back-end reached a hole the shared walk didn't number: a
        structural divergence between the two, surfaced loudly at compile time rather than as a
@@ -121,11 +117,13 @@ export function generateBuild(
     const {
         expression: lowerExpression,
         statement: lowerStatement,
+        script: lowerScript,
         withNestedScripts,
         withShadow,
+        isShadowed,
         bindRead,
         bindWrite,
-    } = lowerContext(stateNames, derivedNames, computedNames, cellReadNames, blockingCellNames)
+    } = lowerContext(stateNames, derivedNames, computedNames, cellReadNames)
 
     /* 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
@@ -285,7 +283,7 @@ export function generateBuild(
                runs as a bind, in document order, so its signals are declared before the later
                siblings that deref them (the enclosing `withNestedScripts` puts those names in
                scope). */
-            binds.push(`${lowerStatement(node.code)}\n`)
+            binds.push(`${lowerScript(node.code)}\n`)
             return ''
         }
         if (node.kind === 'snippet') {
@@ -419,7 +417,7 @@ export function generateBuild(
     /* Emits code appending `node` to `parentVar`. */
     function generateChild(node: TemplateNode, parentVar: string, before = 'null'): string {
         if (node.kind === 'script') {
-            return `${lowerStatement(node.code)}\n`
+            return `${lowerScript(node.code)}\n`
         }
         /* A `<style>` emits no DOM — its CSS is bundled and its scope attribute is
            already stamped onto the elements it covers (see `staticHtml`/`skeletonMarkup`). */
@@ -616,11 +614,11 @@ export function generateBuild(
            cell, so `<Icon>` from `{#for {icon: Icon} of …}` mounts the component the cell
            holds, not the cell object (whose `.build` is undefined → `build is not a
            function`). SSR emits the same lowering for congruence. */
-        /* A hoistable child may have STREAMED (server chose per-render): emit the dual-mode adopter,
-           which probes the cursor to adopt an inlined `[ … ]` range OR a streamed `abide:await`
-           boundary (ADR-0039). Same args as mountChild. */
-        const mountFn = streamCapable.has(node) ? '$$mountStreamedChild' : '$$mountChild'
-        return `${mountFn}(${parentVar}, ${lowerExpression(node.name)}, ${propsArg(node)}, ${before}, ${childOrdinal++});\n`
+        /* `mountChild` is dual-mode (ADR-0039): on hydrate it probes the cursor to adopt an
+           inlined `[ … ]` range OR a streamed `abide:await` boundary, so the client build
+           needs no hoistable-child knowledge — inline-vs-stream is decided server-side per
+           render, and the adopter reads which happened off the markup. */
+        return `$$mountChild(${parentVar}, ${lowerExpression(node.name)}, ${propsArg(node)}, ${before}, ${childOrdinal(node)});\n`
     }
 
     /* An await block: pending → resolved(value) / error branches. Each branch is a
@@ -649,8 +647,11 @@ export function generateBuild(
         const pendingThunk = hasRenderableContent(plan.pending)
             ? branchThunk(plan.pending)
             : 'undefined'
+        /* The subject lowers through the ONE shared ADR-0047 decision site (`awaitSubjectExpr`),
+           so the bare-cell classification can't drift from the SSR back-end's. */
+        const subject = awaitSubjectExpr(node.promise, cellReadNames, isShadowed, lowerExpression)
         return (
-            `$$awaitBlock(${parentVar}, $$nextBlockId(), () => (${lowerExpression(node.promise)}), ` +
+            `$$awaitBlock(${parentVar}, $$nextBlockId(), () => (${subject}), ` +
             `${pendingThunk}, ` +
             `${thenThunk}, ` +
             `${catchThunk}, ${before});\n`

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

@@ -1,5 +1,6 @@
 import { assertExhaustive } from '../../shared/assertExhaustive.ts'
 import { escapeRegex } from '../../shared/escapeRegex.ts'
+import { caseSegment, ELSE_SEGMENT, THEN_SEGMENT } from '../runtime/BRANCH_SEGMENT.ts'
 import { OUTLET_CLOSE, OUTLET_OPEN } from '../runtime/OUTLET_MARKER.ts'
 import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
 import {
@@ -9,6 +10,8 @@ import {
 } from '../runtime/RANGE_MARKER.ts'
 import { asOutlet } from './asOutlet.ts'
 import { awaitPlan } from './awaitPlan.ts'
+import { awaitSubjectExpr } from './awaitSubjectExpr.ts'
+import { componentOrdinals } from './componentOrdinals.ts'
 import { composeProps } from './composeProps.ts'
 import { eachPlan } from './eachPlan.ts'
 import { elementPlan } from './elementPlan.ts'
@@ -74,10 +77,6 @@ export function generateSSR(
     /* Unique temp var names (child render results); runtime block ids are
        allocated separately at runtime via `$ctx.next++`. */
     const nextVar = makeVarNamer()
-    /* A per-body source-order ordinal for each `<Child/>` render site — the render-path segment the
-       child roots under, matching the client `mountChild`'s `childOrdinal` (`generateBuild`) drawn
-       in the identical document-order walk, so both compose the same cell scope ids. */
-    let childOrdinal = 0
 
     /* The enclosing `<select bind:value>`s, innermost last: each carries the JS var holding
        its bound value and whether it's a `multiple` (array) select, so an `<option>` rendered
@@ -88,9 +87,10 @@ export function generateSSR(
     /* The shared signal→`model` lowering + branch-scoped nested-script deref scope. */
     const {
         expression: lowerExpression,
-        statement,
+        script,
         withNestedScripts,
         withShadow,
+        isShadowed,
         bindRead,
         bindWrite,
     } = lowerContext(stateNames, derivedNames, computedNames, cellReadNames)
@@ -102,7 +102,7 @@ export function generateSSR(
 
     /* A scoped-script body for SSR: the shared lowering, then strip effects
        (client-only lifecycle that emits no HTML) — the one SSR-side asymmetry. */
-    const lowerScript = (code: string): string => stripEffects(statement(code))
+    const lowerScript = (code: string): string => stripEffects(script(code))
 
     function push(target: string, literal: string): string {
         return `${target}.push(${JSON.stringify(literal)});\n`
@@ -159,6 +159,13 @@ export function generateSSR(
        through the generic element path exactly as the client clones it. */
     const rootNodes = isLayout ? nodes.map(asOutlet) : nodes
 
+    /* Each `<Child/>` render site's render-path ordinal, from the ONE shared document-order
+       walk the client back-end also reads (`componentOrdinals`) — so both compose the same
+       cell scope ids and streamed-boundary ids regardless of either back-end's emission
+       order. The returned lookup throws on a miss (a structural divergence from the shared
+       walk), surfaced loudly at compile time. */
+    const childOrdinal = componentOrdinals(rootNodes)
+
     /* ADR-0034: the await blocks whose promise-start hoists to the synchronous render prefix so
        independent flights overlap instead of serializing. Server-only — this rewires only the SSR
        promise SOURCE (a blocking `await $flightN`, a streaming `promise: () => $flightN`); the
@@ -362,10 +369,10 @@ export function generateSSR(
                then the `$$readCell` truthy test — so sync and async branches interleave and each
                resolves at render time, mirroring the client `switchBlock` cond-chain. */
             const plan = ifPlan(node)
-            /* The client build lowers a simple `if`/`else` through `when` (branch keys `'then'` /
-               `'else'`) and an `if` with any `elseif` through `switchBlock` over `[then, ...branches]`
-               (branch key = the case's array index). Mirror whichever the client picks so a nested
-               `<Child/>`'s scope id composes identically. */
+            /* The client build lowers a simple `if`/`else` through `when` and an `if` with any
+               `elseif` through `switchBlock` over `[then, ...branches]`. Segments come from the
+               SAME alphabet those runtimes key their branches with (`BRANCH_SEGMENT`), so a
+               nested `<Child/>`'s scope id composes identically — no literal to drift. */
             const clauses: string[] = []
             const conditional = (
                 condition: string,
@@ -385,12 +392,12 @@ export function generateSSR(
                     )
                 }
             }
-            /* `then` is the `when` `'then'` branch, or the `switchBlock` case at index 0. */
+            /* `then` is the `when` then-branch, or the `switchBlock` case at index 0. */
             conditional(
                 node.condition,
                 node.asyncSubject,
                 plan.thenChildren,
-                JSON.stringify(plan.hasElseif ? '0' : 'then'),
+                JSON.stringify(plan.hasElseif ? caseSegment(0) : THEN_SEGMENT),
             )
             for (let index = 0; index < plan.branches.length; index += 1) {
                 const branch = plan.branches[index] as Extract<TemplateNode, { kind: 'case' }>
@@ -401,7 +408,7 @@ export function generateSSR(
                         branch.condition,
                         branch.asyncSubject,
                         branch.children,
-                        JSON.stringify(String(index + 1)),
+                        JSON.stringify(caseSegment(index + 1)),
                     )
                 }
             }
@@ -409,11 +416,11 @@ export function generateSSR(
                 .map((clause, index) => `${index === 0 ? 'if' : ' else if'} ${clause}`)
                 .join('')
             if (plan.elseBranch !== undefined) {
-                /* `else` is the `when` `'else'` branch, or (for a cond-chain) the `switchBlock`
+                /* `else` is the `when` else-branch, or (for a cond-chain) the `switchBlock`
                    default at its own `[then, ...branches]` index. */
                 const elseSegment = plan.hasElseif
-                    ? String(plan.branches.indexOf(plan.elseBranch) + 1)
-                    : 'else'
+                    ? caseSegment(plan.branches.indexOf(plan.elseBranch) + 1)
+                    : ELSE_SEGMENT
                 code += ` else {\n${withPathBranch(JSON.stringify(elseSegment), plan.elseBranch.children, target)}}`
             }
             return `${anchor}${openRange(target)}${code}\n${closeRange(target)}`
@@ -436,12 +443,12 @@ export function generateSSR(
             for (let index = 0; index < plan.cases.length; index += 1) {
                 const branch = plan.cases[index] as Extract<TemplateNode, { kind: 'case' }>
                 if (branch.match !== undefined) {
-                    code += `${started ? 'else ' : ''}if ($s === (${lowerExpression(branch.match)})) {\n${withPathBranch(JSON.stringify(String(index)), branch.children, target)}}\n`
+                    code += `${started ? 'else ' : ''}if ($s === (${lowerExpression(branch.match)})) {\n${withPathBranch(JSON.stringify(caseSegment(index)), branch.children, target)}}\n`
                     started = true
                 }
             }
             if (plan.fallback !== undefined) {
-                const fallbackSegment = String(plan.cases.indexOf(plan.fallback))
+                const fallbackSegment = caseSegment(plan.cases.indexOf(plan.fallback))
                 code += `${started ? 'else ' : ''}{\n${withPathBranch(JSON.stringify(fallbackSegment), plan.fallback.children, target)}}\n`
             }
             if (node.asyncSubject === true) {
@@ -583,10 +590,10 @@ export function generateSSR(
             /* The tag lowers like any reference (see generateBuild): a static import is left bare, a
                reactive/loop/await binding derefs — SSR registers such a binding as `plain`, so it
                reads the bare local holding the resolved component, keeping SSR and client congruent.
-               Root the child's render-path at this mount site's source-order ordinal — the same
+               Root the child's render-path at this mount site's shared-walk ordinal — the same
                segment the client's `mountChild` pushes — so the child's cells and block ids (ADR-0037)
                get an id matching the client's. `$$withPath` sets the path across the child's awaits. */
-            const ordinal = childOrdinal++
+            const ordinal = childOrdinal(node)
             const renderExpr = `$$withPath(${ordinal}, () => ${lowerExpression(node.name)}.render(${propsExpr}, $ctx))`
             if (hoistableChildSet.has(node)) {
                 /* Hoistable (ADR-0037/0039): start the render as an isolated flight in the prefix, and
@@ -595,7 +602,7 @@ export function generateSSR(
                    flight already settled (byte-identical to the old inline await), or a streaming
                    `abide:await:CHILDPATH` boundary + html-only await if it is still pending. The
                    boundary id is the child's render-path (`$$renderPath(ordinal)`), congruent with the
-                   client's `mountStreamedChild`. */
+                   client's dual-mode `mountChild`. */
                 const flightName = `$cf${childFlightCounter++}`
                 childFlightDecls.push(
                     `const ${flightName} = $$flight(() => $$isolateCellBarrier(() => ${renderExpr}));`,
@@ -787,6 +794,12 @@ export function generateSSR(
             : generateStreamingAwait(node, target)
     }
 
+    /* The lowered `{#await X}` subject (ADR-0047) — the ONE shared decision site, so the
+       bare-cell classification can't drift from the client back-end's. Used by the
+       blocking, streaming, and flight-hoist emit sites. */
+    const subjectExprFor = (promiseCode: string): string =>
+        awaitSubjectExpr(promiseCode, cellReadNames, isShadowed, lowerExpression)
+
     /*
     A blocking await — `await`ed at its structural position in the async render pass and
     its resolved branch rendered INLINE into `target`, between the boundary markers. This
@@ -819,7 +832,7 @@ export function generateSSR(
         let code = `const ${id} = $$blockId($ctx);\n`
         code += `${target}.push("<!--abide:await:" + ${id} + "-->");\n`
         code += `try {\n`
-        code += `const ${resolved} = await (${hoistedPromise ?? lowerExpression(node.promise)});\n`
+        code += `const ${resolved} = await (${hoistedPromise ?? subjectExprFor(node.promise)});\n`
         code += `{\n`
         code += `const ${plan.resolvedAs} = ${resolved};\n`
         code += withBindings(withShadow, plan.resolvedBindings, ssrBindingKind, () =>
@@ -891,7 +904,7 @@ export function generateSSR(
         const hoistedPromise = flightNameByNode.get(node)
         code +=
             `$awaits.push({ id: ${id}, ` +
-            `promise: () => (${hoistedPromise ?? lowerExpression(node.promise)}), ` +
+            `promise: () => (${hoistedPromise ?? subjectExprFor(node.promise)}), ` +
             `then: ${settled(plan.resolvedAs, plan.resolvedBindings, plan.resolvedChildren)}, ` +
             `${catchProp}});\n`
         return code
@@ -939,7 +952,7 @@ export function generateSSR(
     const body = generateInto(rootNodes, '$out')
     let flightDecls = ''
     for (const [node, name] of flightNameByNode) {
-        flightDecls += `const ${name} = $$flight(() => (${lowerExpression(node.promise)}));\n`
+        flightDecls += `const ${name} = $$flight(() => (${subjectExprFor(node.promise)}));\n`
     }
     /* Child-render flights emitted during the body walk above (ADR-0037 Phase 2) — appended after
        the await flights; both are independent prefix promise-starts, so order between them is free. */

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

@@ -78,7 +78,7 @@ function walkNode(
         if (
             !conditional &&
             !multiRow &&
-            promiseIsPrefixEvaluable(node.promise, binders, cellReadNames)
+            expressionIsPrefixEvaluable(node.promise, binders, cellReadNames)
         ) {
             flights.push({ node, name: `$flight${counter.next++}` })
         }
@@ -152,16 +152,6 @@ function walkNode(
     }
 }
 
-/* True when EVERY referenced identifier of `promise` is prefix-evaluable: none is a template-local
-   binder and none is an async-cell name. Delegates to the shared `expressionIsPrefixEvaluable`. */
-function promiseIsPrefixEvaluable(
-    promise: string,
-    binders: ReadonlySet<string>,
-    cellReadNames: ReadonlySet<string>,
-): boolean {
-    return expressionIsPrefixEvaluable(promise, binders, cellReadNames)
-}
-
 /* A single-element array literal like `[remountKey]` — the only `{#for}` source that renders its
    body exactly once, so a hoisted flight inside it maps to one row (no shared-flight hazard). */
 function isSingleElementLiteral(items: string): boolean {

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

@@ -1,12 +1,14 @@
 import ts from 'typescript'
 import { classifyInterpolationType } from './classifyInterpolationType.ts'
 
-/* The two TypeScript diagnostics a bare async read (ADR-0032) raises spuriously in a template.
+/* The three TypeScript diagnostics a bare async read (ADR-0032) raises spuriously in a template.
    2339 — a property "missing" on the un-awaited `Promise`/`AsyncIterable`; 2801 — a condition the
-   raw promise makes "always defined". Both are correct against the raw type but wrong against the
-   runtime PEEK (the resolved value, `undefined` while pending), which the shadow can't see. */
+   raw promise makes "always defined"; 2488 — a promise source "not iterable" in a plain `{#for}`.
+   All are correct against the raw type but wrong against the runtime PEEK (the resolved value,
+   `undefined` while pending), which the shadow can't see. */
 const PROPERTY_DOES_NOT_EXIST = 2339
 const CONDITION_ALWAYS_DEFINED = 2801
+const SOURCE_NOT_ITERABLE = 2488
 
 /*
 Whether a shadow diagnostic is one the ADR-0032 bare-async-read peek makes spurious. The runtime
@@ -20,11 +22,16 @@ caller can drop them:
     property EXISTS on the awaited (promise) or frame (iterable) type — the peek's real member.
   - 2801 (always-defined condition): the flagged subject itself classifies as a promise/iterable —
     the peek is genuinely nullable (pending → `undefined`), so it is not always-defined.
+  - 2488 (source not iterable): a plain `{#for}` source classifies as a promise whose AWAITED type
+    is itself iterable — the runtime lifts it to a peek-cell reading the resolved collection (empty
+    while pending), so iterating it is valid (matches `typeDirectedInterpolation`'s peek-cell lift).
 
-Deliberately narrow so it never hides a real mistake: only these two codes; 2339 only via `?.`
+Deliberately narrow so it never hides a real mistake: only these three codes; 2339 only via `?.`
 (a bare `.name` on a promise stays an error, nudging toward the `?.` the peek needs) and only when
 the property resolves on the awaited/frame type (a typo `?.namex` stays); 2801 only when the
-subject is actually async (a bare `{#if someFn}` — a forgotten call — stays). Callers additionally
+subject is actually async (a bare `{#if someFn}` — a forgotten call — stays); 2488 only for a
+PROMISE whose awaited type is iterable (a raw `AsyncIterable` source stays the sanctioned D4a error,
+and a `Promise<number>` source stays a real mistake the peek can't rescue). Callers additionally
 gate on the diagnostic mapping into the template region, so `<script>` code (where a forgotten
 `await` must surface) is never touched.
 */
@@ -41,6 +48,40 @@ export function isSpuriousAsyncReadDiagnostic(
     if (code === CONDITION_ALWAYS_DEFINED) {
         return isAsyncSubject(shadowFile, checker, start, length)
     }
+    if (code === SOURCE_NOT_ITERABLE) {
+        return isResolvedIterableAsyncSource(shadowFile, checker, start, length)
+    }
+    return false
+}
+
+/* A 2488 on a plain `{#for}` source whose expression classifies as a PROMISE and whose awaited
+   type is itself iterable — the ADR-0032 peek lifts it to the resolved collection, not an error.
+   Excludes a raw `AsyncIterable` (kind `asyncIterable`, the D4a error) and a promise of a
+   non-iterable (the peek would still not iterate). */
+function isResolvedIterableAsyncSource(
+    shadowFile: ts.SourceFile,
+    checker: ts.TypeChecker,
+    start: number,
+    length: number,
+): boolean {
+    const source = deepestNodeAt(shadowFile, start, length)
+    const sourceType = checker.getTypeAtLocation(source)
+    if (classifyInterpolationType(sourceType, source, checker) !== 'promise') {
+        return false
+    }
+    const awaited = checker.getAwaitedType(sourceType)
+    return awaited !== undefined && hasSyncIterator(awaited, checker)
+}
+
+/* Whether a type is synchronously iterable — an array/tuple or anything carrying the well-known
+   `Symbol.iterator` member (mangled to `__@iterator@<id>`, matched by prefix like
+   `classifyInterpolationType`'s async twin). */
+function hasSyncIterator(type: ts.Type, checker: ts.TypeChecker): boolean {
+    for (const property of checker.getPropertiesOfType(type)) {
+        if ((property.escapedName as string).startsWith('__@iterator')) {
+            return true
+        }
+    }
     return false
 }
 

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

@@ -6,6 +6,7 @@ import { signalRefsTransformer } from './renameSignalRefs.ts'
 import { TS_PRINTER } from './TS_PRINTER.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import { unwrapParens } from './unwrapParens.ts'
+import { wrapReactiveSeedsTransformer } from './wrapReactiveSeeds.ts'
 
 /* Compiled once — strips the trailing `;` off every lowered expression. */
 const TRAILING_SEMICOLON = /;$/
@@ -25,11 +26,10 @@ export function lowerContext(
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
     computedNames: ReadonlySet<string> = new Set(),
-    /* `linked` / async `computed` names, read through `$$readCell(name)`. */
+    /* `linked` / async `computed` names, read through `$$readCell(name)` — one read form
+       whose pause-vs-peek is decided at runtime by the cell's own `blocking` bit (ADR-0042),
+       so both back-ends lower a cell read identically with nothing site-specific to thread. */
     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
@@ -44,9 +44,13 @@ export function lowerContext(
        one tree — the two string passes would each parse + reprint. `localDerived` is
        snapshotted per call (as the transformer's block-local shadow set) so a binding
        pushed mid-compile is honoured AND shadows a same-named component signal. */
-    function lowerOnce(code: string): string {
+    function lowerOnce(
+        code: string,
+        leadingTransformers: ts.TransformerFactory<ts.SourceFile>[] = [],
+    ): string {
         const source = ts.createSourceFile('expr.ts', code, ts.ScriptTarget.Latest, true)
         const result = ts.transform(source, [
+            ...leadingTransformers,
             signalRefsTransformer(
                 stateNames,
                 derivedNames,
@@ -54,7 +58,6 @@ export function lowerContext(
                 new Set(scope.names('derived')),
                 new Set(scope.names('plain')),
                 cellReadNames,
-                blockingCellNames,
             ),
             docAccessTransformer('$$model'),
         ])
@@ -75,6 +78,16 @@ export function lowerContext(
         return lowerOnce(code)
     }
 
+    /* A nested branch `<script>` body. Same lowering as `statement`, but first normalises its
+       literal `state.computed`/`state.linked` seeds into thunks (`wrapReactiveSeeds`) so a bare-
+       value seed (`state.computed(a * 2)`) matches the top-level desugar rather than reaching the
+       runtime primitive un-thunked (which would call the value as the compute function and crash).
+       The wrap runs BEFORE the reference rename so it wraps the raw seed and the renamed refs land
+       inside the thunk. */
+    function script(code: string): string {
+        return lowerOnce(code, [wrapReactiveSeedsTransformer()])
+    }
+
     /* A two-way bind target is either an LVALUE (`count`, `model.lines[i]`) — reads as
        itself, writes by assignment — or an ACCESSOR object from `bind:value={{ get, set }}`
        — reads via `.get()`, writes via `.set(v)`. The accessor is the only way to bind a
@@ -136,11 +149,18 @@ export function lowerContext(
     return {
         expression,
         statement,
+        script,
         withNestedScripts,
         /* The raw branch-local shadow registration both back-ends drive `withBindings`
            through: a block's bindings flow to a `ShadowKind` only via that one shared loop,
            never through a per-block `scope.withShadow` call here. */
         withShadow: scope.withShadow,
+        /* Whether `name` is currently shadowed by a block binding (either kind) at this point
+           of the walk — the live query classification sites (e.g. `awaitSubjectExpr`) consult
+           so a binder that shadows a component cell name is lowered as the local it is, never
+           wrapped as the cell it hides. */
+        isShadowed: (name: string): boolean =>
+            scope.names('plain').has(name) || scope.names('derived').has(name),
         bindRead,
         bindWrite,
     }