@abide/abide 0.54.0 → 0.55.0

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

@@ -120,7 +120,6 @@ export function analyzeComponent(
         derivedNames,
         computedNames,
         cellReadNames,
-        blockingCellNames: allBlockingCellNames,
         droppedReactiveImports,
     } = lowerScript(
         fullScriptBody,
@@ -143,7 +142,6 @@ 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/awaitSubjectExpr.ts

@@ -0,0 +1,23 @@
+/*
+The lowered `{#await X}` subject, normalised so a cell subject AWAITS its resolution
+(ADR-0047): a BARE async-cell reference is passed RAW (not peeked to `$$readCell(cell)`)
+and wrapped in `$$awaitSubject(...)`, which resolves a cell to a promise-of-its-value —
+so `{#await rates}` (a cell) shows pending then the value; any other subject lowers
+unchanged, so `{#await getFoo()}` (a plain promise) is byte-identical. A name currently
+SHADOWED by a block binding (`{#for rates of …}` / `{:then rates}` over a component cell
+`rates`) is the binder's local, not the cell — it lowers through `lowerExpression` like any
+other subject, matching how every other reference site honours the shadow stack. ONE
+decision site shared by both back-ends (the client `awaitBlock` emit and SSR's blocking /
+streaming / flight-hoist emits), so the bare-cell classification can't drift between them.
+*/
+export function awaitSubjectExpr(
+    promiseCode: string,
+    cellReadNames: ReadonlySet<string>,
+    isShadowed: (name: string) => boolean,
+    lowerExpression: (code: string) => string,
+): string {
+    const bare = promiseCode.trim()
+    return cellReadNames.has(bare) && !isShadowed(bare)
+        ? `$$awaitSubject(${bare})`
+        : lowerExpression(promiseCode)
+}

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

@@ -1,3 +1,4 @@
+import { messageFromError } from '../../shared/messageFromError.ts'
 import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
 
 /*
@@ -26,7 +27,7 @@ export function cachedShadowProgram(
             cache.set(root, build(root))
         } catch (error) {
             cache.set(root, undefined)
-            const detail = error instanceof Error ? error.message : String(error)
+            const detail = messageFromError(error)
             console.warn(
                 `[abide] couldn't build the type program for ${root}: ${detail}\n` +
                     '  type-directed async detection is disabled for this project — a bare promise/stream\n' +

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

@@ -29,15 +29,7 @@ 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,
-        blockingCellNames,
-        nodes,
-    } = resolved
+    const { script, stateNames, derivedNames, computedNames, cellReadNames, nodes } = resolved
     const build = generateBuild(
         nodes,
         'host',
@@ -46,7 +38,6 @@ 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/componentOrdinals.ts

@@ -0,0 +1,39 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/*
+Document-order (pre-order) numbering of every `<Child/>` mount site in a template — the
+ordinal a child's render-path roots under (`mountChild` on the client, `$$withPath(ordinal)`
+/ `$$renderPath(ordinal)` on the server). ONE walk both back-ends read (the `skeletonContext`
+pattern), replacing the per-back-end `childOrdinal++` counters that numbered components in
+each generator's own EMISSION order — an order that could silently diverge (build emits a
+component's slot content before taking its own ordinal; SSR emits a switch's default case
+after later cases). Numbering from the tree, not the emission, makes SSR↔client ordinal
+congruence hold by construction.
+
+Returns the lookup, not the map, so the missing-entry policy lives here too: a miss means a
+back-end reached a mount site the shared walk didn't number — a structural divergence,
+surfaced loudly at compile time rather than as a runtime warm-seed/boundary desync.
+*/
+export function componentOrdinals(nodes: TemplateNode[]): (node: TemplateNode) => number {
+    const ordinals = new WeakMap<TemplateNode, number>()
+    let next = 0
+    const walk = (children: TemplateNode[]): void => {
+        for (const child of children) {
+            if (child.kind === 'component') {
+                ordinals.set(child, next)
+                next += 1
+            }
+            if ('children' in child) {
+                walk(child.children)
+            }
+        }
+    }
+    walk(nodes)
+    return (node: TemplateNode): number => {
+        const ordinal = ordinals.get(node)
+        if (ordinal === undefined) {
+            throw new Error('[abide] component mount site not numbered by the shared ordinal walk')
+        }
+        return ordinal
+    }
+}

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

@@ -5,6 +5,7 @@ import { type ReactiveImportBindings, reactiveImportBindings } from './resolveRe
 import { signalCallee } from './signalCallee.ts'
 import type { InterpolationKind } from './types/InterpolationKind.ts'
 import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
+import { wrapSeed } from './wrapSeed.ts'
 
 /* The routing decision for a no-marker `computed(seed)`: `true` routes to the eager
    `trackedComputed` stream cell (read via `$$readCell`, the `cellReadNames` bucket), `false`
@@ -14,28 +15,6 @@ type EagerStreamPredicate = (declaration: ts.VariableDeclaration) => boolean
 
 const factory = ts.factory
 
-/* 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
-   expression contains a top-level `await` (`computed(await load())` → `async () => await
-   load()`), which is exactly the marker the runtime primitive uses to route to an async cell. */
-function wrapSeed(argument: ts.Expression): ts.Expression {
-    if (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)) {
-        return argument
-    }
-    const modifiers = hasTopLevelAwait(argument)
-        ? [factory.createModifier(ts.SyntaxKind.AsyncKeyword)]
-        : undefined
-    return factory.createArrowFunction(
-        modifiers,
-        undefined,
-        [],
-        undefined,
-        factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-        argument,
-    )
-}
-
 /* 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
@@ -231,10 +210,6 @@ 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
@@ -253,10 +228,6 @@ 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
@@ -359,27 +330,21 @@ export function desugarSignals(
                     isEagerStreamComputed(declaration) ||
                     isPromiseComputed(declaration)
                 ) {
+                    /* Async `computed` (author `await`), an eager stream, or a promise seed — all
+                       read via `$$readCell(name)`. Whether a pending read PAUSES (author `await`,
+                       a blocking cell) or peeks `undefined` (streaming) is carried by the cell
+                       itself at construction (the `trackedComputed(thunk, streaming)` flag), so the
+                       read form is uniform and nothing blocking-specific is collected here. */
                     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)
                 }
             } else if (callee === 'linked') {
                 /* `linked` → a cell read via `$$readCell(name)`: a plain `State` when the seed
                    is synchronous, an `AsyncState` when it tracks a promise/stream — one read
-                   shape auto-tracks whichever source the runtime primitive resolved to. */
+                   shape auto-tracks whichever source the runtime primitive resolved to. Its
+                   blocking-ness (author `await`) likewise rides on the constructed cell. */
                 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. */
@@ -441,7 +406,6 @@ export function desugarSignals(
         derivedNames,
         computedNames,
         cellReadNames,
-        blockingCellNames: new Set([...blockingCellNames, ...scriptBlockingNames]),
     }
 }
 

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