@barefootjs/jsx 0.26.2 → 0.26.4

package/src/jsx-to-ir.ts

@@ -26,7 +26,10 @@ import {
   type LoopBindingPathSegment,
   type RestExcludeKey,
   type FlatMapCallback,
-  type FlatMapJsxFragment,
+  type MapCallbackPreamble,
+  type PreambleSegment,
+  type PreambleRegionSource,
+  tsxSourceText,
   type SourceLocation,
   type TypeInfo,
   type OriginInfo,
@@ -48,11 +51,13 @@ import {
 import { resolveFreeRefs, isNameBound as isNameBoundInEnv, type BindingEnvironment } from './free-refs.ts'
 import { computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { createTemplateAwareStringProtector } from './ir-to-client-js/html-template.ts'
+import { extractFreeIdentifiersFromText } from './ir-to-client-js/csr-substitute.ts'
 import { datePlugin, DATE_METHODS } from './date-lowering.ts'
 import { toLocaleDatePlugin, foldedArgToClientJs } from './to-locale-date-lowering.ts'
 import type { LoweringMatcher } from './lowering-registry.ts'
-import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx } from './analyzer.ts'
+import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx, extractMultiReturnJsxBranches, type MultiReturnJsxBranches } from './analyzer.ts'
 import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
+import { reconstructAsSegments } from './strip-types.ts'
 import { toHTMLAttrName, decodeEntities } from '@barefootjs/shared'
 
 // =============================================================================
@@ -909,8 +914,12 @@ function attachParsedExpressions(node: IRNode, analyzer: AnalyzerContext, bound:
       for (const nested of node.nestedComponents ?? []) {
         for (const child of nested.children) attachParsedExpressions(child, analyzer, loopBound)
       }
-      for (const frag of node.flatMapCallback?.fragments ?? []) {
-        attachParsedExpressions(frag.ir, analyzer, loopBound)
+      for (const seg of node.flatMapCallback?.segments ?? []) {
+        if (seg.kind === 'jsx') attachParsedExpressions(seg.ir, analyzer, loopBound)
+      }
+      // Preamble leaves (array-builder bodies) are nested IR the same way.
+      for (const seg of node.preamble?.segments ?? []) {
+        if (seg.kind === 'jsx') attachParsedExpressions(seg.ir, analyzer, loopBound)
       }
       break
     }
@@ -2119,100 +2128,132 @@ function transformMultiReturnJsxFunctionCall(
 
   try {
     const loc = getSourceLocation(callExpr, ctx.sourceFile, ctx.filePath)
-    const nullExpr: IRExpression = {
-      type: 'expression',
-      expr: 'null',
-      typeInfo: { kind: 'primitive', raw: 'null', primitive: 'null' },
-      reactive: false,
-      slotId: null,
-      loc,
-      origin: { phase: 'tick', scope: 'template', effect: 'pure', freeRefs: [] },
+    return foldMultiReturnBranches(info, ctx, loc, substitutedGetJS)
+  } finally {
+    ctx.getJS = originalCtxGetJS
+    ctx.analyzer.getJS = originalAnalyzerGetJS
+  }
+}
+
+/**
+ * Fold an extracted multi-return branch structure (if/else-if chain or switch)
+ * into a right-nested chain of `IRConditional` nodes, terminating in the
+ * fallback (or `null`). Shared by the helper-function inliner
+ * (`transformMultiReturnJsxFunctionCall`, which swaps `ctx.getJS` for a
+ * param-substituting variant first) and the `.map()` callback-body fold
+ * (Stage 2 of `spec/callback-fidelity.md`), which folds branches in the
+ * loop-body context where the item binding is already in scope — no
+ * substitution. `getText` stringifies condition / discriminant expressions
+ * (the substituting variant for the former, `ctx.getJS` for the latter);
+ * branch JSX is transformed via `transformNode`, which reads the (possibly
+ * swapped) `ctx.getJS`.
+ */
+function foldMultiReturnBranches(
+  info: MultiReturnJsxBranches,
+  ctx: TransformContext,
+  loc: SourceLocation,
+  getText: (node: ts.Node) => string,
+): IRNode {
+  const nullExpr: IRExpression = {
+    type: 'expression',
+    expr: 'null',
+    typeInfo: { kind: 'primitive', raw: 'null', primitive: 'null' },
+    reactive: false,
+    slotId: null,
+    loc,
+    origin: { phase: 'tick', scope: 'template', effect: 'pure', freeRefs: [] },
+  }
+
+  // Build the conditional chain from bottom up (last branch → first branch)
+  let result: IRNode = info.fallback
+    ? (transformNode(info.fallback, ctx) ?? nullExpr)
+    : nullExpr
+
+  for (let i = info.branches.length - 1; i >= 0; i--) {
+    const branch = info.branches[i]
+
+    // A switch fallthrough (`case 'a': case 'b': return X`) yields one branch
+    // covering several case labels — OR-join them into `disc === a ||
+    // disc === b`. A plain if-branch or a single case is just `[condition]`.
+    const caseConds = info.switchDiscriminant
+      ? [branch.condition, ...(branch.extraCaseConditions ?? [])]
+      : [branch.condition]
+
+    // Build condition text (`getText` applies param substitution when the
+    // helper-function inliner supplies a substituting variant).
+    let conditionText: string
+    if (info.switchDiscriminant) {
+      const discText = getText(info.switchDiscriminant)
+      // Parenthesize both operands so a low-precedence case expression
+      // (`case a ?? b:`, a ternary, …) keeps strict-equality semantics rather
+      // than binding as `(disc === a) ?? b`. (#2377 review.)
+      conditionText = caseConds.map(c => `(${discText}) === (${getText(c)})`).join(' || ')
+    } else {
+      conditionText = getText(branch.condition)
     }
 
-    // Build the conditional chain from bottom up (last branch → first branch)
-    let result: IRNode = info.fallback
-      ? (transformNode(info.fallback, ctx) ?? nullExpr)
+    // For switch-sourced conditions, merge freeRefs/reactivity from the
+    // discriminant and every case expression so prop rewrites and reactivity
+    // detection cover the full `disc === a || disc === b` condition.
+    const env = makeBindingEnv(ctx)
+    const caseFreeRefs = caseConds.flatMap(c => resolveFreeRefs(c, env))
+    const discFreeRefs = info.switchDiscriminant
+      ? resolveFreeRefs(info.switchDiscriminant, env)
+      : []
+    const conditionOrigin: OriginInfo = {
+      phase: 'tick',
+      scope: 'template',
+      effect: 'pure',
+      freeRefs: [...discFreeRefs, ...caseFreeRefs],
+    }
+    const reactive = isReactiveExpression(conditionText, ctx, branch.condition)
+      || isReactiveOrigin(conditionOrigin)
+    const loopParamReactive = !reactive && referencesLoopParam(conditionText, ctx)
+    const callsReactive = caseConds.some(c => exprCallsReactiveGetters(c, ctx))
+      || (info.switchDiscriminant ? exprCallsReactiveGetters(info.switchDiscriminant, ctx) : false)
+    const hasCalls = caseConds.some(c => exprHasFunctionCalls(c))
+      || (info.switchDiscriminant ? exprHasFunctionCalls(info.switchDiscriminant) : false)
+    const needsSlot = reactive || loopParamReactive || callsReactive || hasCalls
+    const slotId = needsSlot ? generateSlotId(ctx) : null
+
+    const whenTrue = branch.jsxReturn
+      ? (transformNode(branch.jsxReturn, ctx) ?? nullExpr)
       : nullExpr
 
-    for (let i = info.branches.length - 1; i >= 0; i--) {
-      const branch = info.branches[i]
-
-      // Build condition text with param substitution
-      let conditionText: string
-      if (info.switchDiscriminant) {
-        const discText = substitutedGetJS(info.switchDiscriminant)
-        const caseText = substitutedGetJS(branch.condition)
-        conditionText = `${discText} === ${caseText}`
-      } else {
-        conditionText = substitutedGetJS(branch.condition)
-      }
-
-      // For switch-sourced conditions, merge freeRefs/reactivity from
-      // both the discriminant and case expression so prop rewrites and
-      // reactivity detection cover the full `disc === case` condition.
-      const env = makeBindingEnv(ctx)
-      const caseFreeRefs = resolveFreeRefs(branch.condition, env)
-      const discFreeRefs = info.switchDiscriminant
-        ? resolveFreeRefs(info.switchDiscriminant, env)
-        : []
-      const conditionOrigin: OriginInfo = {
-        phase: 'tick',
-        scope: 'template',
-        effect: 'pure',
-        freeRefs: [...discFreeRefs, ...caseFreeRefs],
-      }
-      const reactive = isReactiveExpression(conditionText, ctx, branch.condition)
-        || isReactiveOrigin(conditionOrigin)
-      const loopParamReactive = !reactive && referencesLoopParam(conditionText, ctx)
-      const callsReactive = exprCallsReactiveGetters(branch.condition, ctx)
-        || (info.switchDiscriminant ? exprCallsReactiveGetters(info.switchDiscriminant, ctx) : false)
-      const hasCalls = exprHasFunctionCalls(branch.condition)
-        || (info.switchDiscriminant ? exprHasFunctionCalls(info.switchDiscriminant) : false)
-      const needsSlot = reactive || loopParamReactive || callsReactive || hasCalls
-      const slotId = needsSlot ? generateSlotId(ctx) : null
-
-      const whenTrue = branch.jsxReturn
-        ? (transformNode(branch.jsxReturn, ctx) ?? nullExpr)
-        : nullExpr
-
-      // For switch conditions, build templateCondition from both parts
-      let templateCondition: string | undefined
-      if (info.switchDiscriminant) {
-        const discRewritten = rewriteBarePropRefs(
-          substitutedGetJS(info.switchDiscriminant), info.switchDiscriminant, ctx
-        )
-        const caseRewritten = rewriteBarePropRefs(
-          substitutedGetJS(branch.condition), branch.condition, ctx
-        )
-        const discPart = discRewritten ?? substitutedGetJS(info.switchDiscriminant)
-        const casePart = caseRewritten ?? substitutedGetJS(branch.condition)
-        templateCondition = `${discPart} === ${casePart}`
-      } else {
-        templateCondition = rewriteBarePropRefs(conditionText, branch.condition, ctx)
-      }
-
-      const conditional: IRConditional = {
-        type: 'conditional',
-        condition: conditionText,
-        templateCondition,
-        conditionType: null,
-        reactive,
-        whenTrue,
-        whenFalse: result,
-        slotId,
-        callsReactiveGetters: callsReactive || undefined,
-        hasFunctionCalls: hasCalls || undefined,
-        loc,
-        origin: conditionOrigin,
-      }
-      result = conditional
+    // For switch conditions, build templateCondition from the discriminant and
+    // every (prop-rewritten) case label, OR-joined for fallthrough.
+    let templateCondition: string | undefined
+    if (info.switchDiscriminant) {
+      const discRewritten = rewriteBarePropRefs(
+        getText(info.switchDiscriminant), info.switchDiscriminant, ctx
+      )
+      const discPart = discRewritten ?? getText(info.switchDiscriminant)
+      templateCondition = caseConds.map(c => {
+        const casePart = rewriteBarePropRefs(getText(c), c, ctx) ?? getText(c)
+        return `(${discPart}) === (${casePart})`
+      }).join(' || ')
+    } else {
+      templateCondition = rewriteBarePropRefs(conditionText, branch.condition, ctx)
     }
 
-    return result
-  } finally {
-    ctx.getJS = originalCtxGetJS
-    ctx.analyzer.getJS = originalAnalyzerGetJS
+    const conditional: IRConditional = {
+      type: 'conditional',
+      condition: conditionText,
+      templateCondition,
+      conditionType: null,
+      reactive,
+      whenTrue,
+      whenFalse: result,
+      slotId,
+      callsReactiveGetters: callsReactive || undefined,
+      hasFunctionCalls: hasCalls || undefined,
+      loc,
+      origin: conditionOrigin,
+    }
+    result = conditional
   }
+
+  return result
 }
 
 function transformConditional(
@@ -3597,6 +3638,99 @@ function checkLoopKey(
  * item; multi-root bodies (e.g. `<><path/><path/></>`) need per-item
  * boundary markers and multi-root template cloning (#1212).
  */
+/**
+ * Recognize a flatMap PROJECTION body: a bare map-like call
+ * (`it.tags.map(...)` / nested `.flatMap(...)`) as the whole body — either
+ * an expression body (parenthesized or not) or a block whose ONLY statement
+ * is `return <call>`. Anything carrying additional statements does not
+ * qualify (it rides the structured-segments carrier instead). Returns the
+ * call expression to lower as the loop's nested-loop child, or null.
+ */
+function flatMapProjectionCall(body: ts.ConciseBody): ts.CallExpression | null {
+  let expr: ts.Expression | undefined
+  if (ts.isBlock(body)) {
+    const real = body.statements
+    if (real.length !== 1 || !ts.isReturnStatement(real[0]) || !real[0].expression) return null
+    expr = real[0].expression
+  } else {
+    expr = body
+  }
+  while (ts.isParenthesizedExpression(expr)) expr = expr.expression
+  if (!ts.isCallExpression(expr)) return null
+  if (!getMapLikeMethod(expr)) return null
+  // The descriptor synthesis renders the inner callback's raw params into
+  // the client accessor (`.map((tag, i) => ({ k, h }))`), which is only
+  // sound for plain-identifier params — a destructure pattern rides the
+  // segments carrier instead.
+  const cb = expr.arguments[0]
+  if (!cb || (!ts.isArrowFunction(cb) && !ts.isFunctionExpression(cb))) return null
+  for (const p of cb.parameters) {
+    if (!ts.isIdentifier(p.name)) return null
+  }
+  // The client descriptor is one element per flattened leaf, so the inner
+  // callback must produce a single element root (a JSX element, or a ternary
+  // whose branches are elements). Fragments / array literals ride the
+  // segments carrier.
+  let innerBody: ts.Node = cb.body
+  if (ts.isBlock(innerBody)) {
+    const ret = innerBody.statements.find(
+      (s): s is ts.ReturnStatement => ts.isReturnStatement(s) && s.expression != null,
+    )
+    if (innerBody.statements.length !== 1 || !ret?.expression) return null
+    innerBody = ret.expression
+  }
+  while (ts.isParenthesizedExpression(innerBody)) innerBody = innerBody.expression
+  const isElementish = (n: ts.Node): boolean => {
+    let m = n
+    while (ts.isParenthesizedExpression(m)) m = m.expression
+    if (ts.isJsxElement(m) || ts.isJsxSelfClosingElement(m)) return leafIsWirelessElement(m)
+    if (ts.isConditionalExpression(m)) return isElementish(m.whenTrue) && isElementish(m.whenFalse)
+    return false
+  }
+  if (!isElementish(innerBody)) return null
+  return expr
+}
+
+/**
+ * Syntactic pre-check that a projection leaf carries no per-element wiring —
+ * no event handlers, spreads, component tags, or nested JSX-bearing loops.
+ * Runs BEFORE the leaf is transformed (the accept/reject decision must not
+ * leave transform side effects — slot ids, collected events — behind when
+ * the shape falls back to the segments carrier, whose own transform would
+ * then double-register them).
+ */
+function leafIsWirelessElement(el: ts.JsxElement | ts.JsxSelfClosingElement): boolean {
+  let ok = true
+  const visit = (n: ts.Node): void => {
+    if (!ok) return
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+      // Only a lowercase plain identifier (or a namespaced name like
+      // `svg:path`) is an intrinsic element. A member/this tag
+      // (`<icons.Tag/>`, `<this.Tag/>`) is a component per JSX semantics
+      // regardless of case — the case test alone would let it through.
+      const tagNode = n.tagName
+      const isIntrinsic = ts.isIdentifier(tagNode)
+        ? !/^[A-Z]/.test(tagNode.text)
+        : ts.isJsxNamespacedName(tagNode)
+      if (!isIntrinsic) { ok = false; return }
+      for (const attr of n.attributes.properties) {
+        if (ts.isJsxSpreadAttribute(attr)) { ok = false; return }
+        if (ts.isJsxAttribute(attr)) {
+          const name = attr.name.getText()
+          if (/^on[A-Z]/.test(name)) { ok = false; return }
+        }
+      }
+    }
+    if (ts.isCallExpression(n) && getMapLikeMethod(n) && containsJsxInExpression(n)) {
+      ok = false
+      return
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(el)
+  return ok
+}
+
 function loopBodyIsMultiRoot(children: IRNode[]): boolean {
   const real = children.filter(
     (c) => !(c.type === 'text' && typeof c.value === 'string' && !c.value.trim())
@@ -3680,6 +3814,10 @@ function transformMapCall(
   // Capture nesting depth before we register this map's own params.
   // ctx.loopParams is populated by the *outer* map; if non-empty we are inside one.
   const isNested = ctx.loopParams.size > 0
+  // Diagnostic count at entry — the structural net at the scalar fallthrough
+  // de-dups against refusals fired DURING this call (leaf-wiring, DSL gates),
+  // never against unrelated diagnostics recorded before it.
+  const diagCountAtEntry = ctx.analyzer.errors.length
   // This loop's own depth (0 = outermost) is however many enclosing
   // loops are already active, captured before `ctx.loopDepth` below is
   // bumped for THIS loop's own descendants.
@@ -3705,9 +3843,10 @@ function transformMapCall(
   let filterPredicate: FilterPredicateResult | undefined
   let sortComparator: IRLoopSort | undefined
   let chainOrder: 'filter-sort' | 'sort-filter' | undefined
-  let mapPreamble: string | undefined
-  let templateMapPreamble: string | undefined
-  let typedMapPreamble: string | undefined
+  // Structured pre-return statements of a block-body callback (Stage 3 root
+  // cure): JS text + compiled JSX leaves as segments, plus the raw TSX for
+  // JSX-runtime SSR and the declared names (D5 key guard, {out} join).
+  let preamble: MapCallbackPreamble | undefined
   let iterationShape: 'entries' | 'keys' | undefined
   let objectIteration: 'entries' | 'keys' | 'values' | undefined
 
@@ -3761,7 +3900,12 @@ function transformMapCall(
     // Handle sort comparator extraction
     const sortExtraction = extractSortComparator(sortInfo.callback, sortInfo.method, ctx)
     if (isClientOnly || !sortExtraction.result) {
-      if (!isClientOnly && sortExtraction.unsupportedReason) {
+      // Off-subset comparator: keep it in the array string for client / SSR
+      // evaluation. Only raise the diagnostic when the target adapter's runtime
+      // can't run the comparator body verbatim (DSL); a JS-runtime adapter runs
+      // it, so rejecting it would be a universal error for a DSL-only limit.
+      // See spec/callback-fidelity.md.
+      if (!isClientOnly && sortExtraction.unsupportedReason && !(ctx.analyzer.acceptsCallbackBody?.('sort') ?? false)) {
         ctx.analyzer.errors.push(
           createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN,
             getSourceLocation(sortInfo.callback, ctx.sourceFile, ctx.filePath),
@@ -3784,7 +3928,11 @@ function transformMapCall(
         chainOrder = 'filter-sort'
         const filterExtraction = extractFilterPredicate(innerFilter.callback, ctx)
         if (isClientOnly || !filterExtraction.result) {
-          if (!isClientOnly && filterExtraction.unsupportedReason) {
+          // Off-subset predicate: keep it in the array string for client / SSR
+          // evaluation. Only raise the diagnostic when the target adapter's runtime
+          // can't run the predicate body verbatim (DSL); a JS-runtime adapter runs
+          // it. See spec/callback-fidelity.md.
+          if (!isClientOnly && filterExtraction.unsupportedReason && !(ctx.analyzer.acceptsCallbackBody?.('filter') ?? false)) {
             ctx.analyzer.errors.push(
               createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN,
                 getSourceLocation(innerFilter.callback, ctx.sourceFile, ctx.filePath),
@@ -3818,7 +3966,11 @@ function transformMapCall(
     const filterExtraction = extractFilterPredicate(filterInfo.callback, ctx)
 
     if (isClientOnly || !filterExtraction.result) {
-      if (!isClientOnly && filterExtraction.unsupportedReason) {
+      // Off-subset predicate: keep it in the array string for client / SSR
+      // evaluation. Only raise the diagnostic when the target adapter's runtime
+      // can't run the predicate body verbatim (DSL); a JS-runtime adapter runs
+      // it. See spec/callback-fidelity.md.
+      if (!isClientOnly && filterExtraction.unsupportedReason && !(ctx.analyzer.acceptsCallbackBody?.('filter') ?? false)) {
         ctx.analyzer.errors.push(
           createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN,
             getSourceLocation(filterInfo.callback, ctx.sourceFile, ctx.filePath),
@@ -3841,7 +3993,12 @@ function transformMapCall(
         chainOrder = 'sort-filter'
         const sortExtraction = extractSortComparator(innerSort.callback, innerSort.method, ctx)
         if (isClientOnly || !sortExtraction.result) {
-          if (!isClientOnly && sortExtraction.unsupportedReason) {
+          // Off-subset comparator: keep it in the array string for client / SSR
+          // evaluation. Only raise the diagnostic when the target adapter's runtime
+          // can't run the comparator body verbatim (DSL); a JS-runtime adapter runs
+          // it, so rejecting it would be a universal error for a DSL-only limit.
+          // See spec/callback-fidelity.md.
+          if (!isClientOnly && sortExtraction.unsupportedReason && !(ctx.analyzer.acceptsCallbackBody?.('sort') ?? false)) {
             ctx.analyzer.errors.push(
               createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN,
                 getSourceLocation(innerSort.callback, ctx.sourceFile, ctx.filePath),
@@ -4032,10 +4189,58 @@ function transformMapCall(
       // flatMap arrow with array literal: items.flatMap(item => [<A/>, <B/>])
       children = transformArrayLiteralChildren(body, ctx)
     } else if (ts.isBlock(body)) {
+      // Multi-return JSX block body (if/else-if chain or a `switch`, including
+      // fallthrough case labels, optionally preceded by a `const`/`let`
+      // preamble) — fold to a nested IRConditional so the loop renders each
+      // branch's compiled template. Tried BEFORE the single-return path:
+      // otherwise the trailing `return <fallback/>` would claim the
+      // single-return arm and the leading `if (...) return <A/>` would leak
+      // verbatim into the map preamble (the silent-verbatim-leak this fixes).
+      // Stage 2 of spec/callback-fidelity.md. A branch-local `const` (inside a
+      // branch block/case) or a statement-level nested loop is not folded
+      // (extractMultiReturnJsxBranches returns null) and falls through below.
+      const multiReturn = method !== 'flatMap' ? extractMultiReturnJsxBranches(body, true) : null
+      if (multiReturn && multiReturn.branches.length > 0) {
+        const loc = getSourceLocation(body, ctx.sourceFile, ctx.filePath)
+        children = [foldMultiReturnBranches(multiReturn, ctx, loc, ctx.getJS)]
+
+        const pre = multiReturn.preamble ?? []
+        if (pre.length > 0) {
+          // Emit the leading const/let preamble once per iteration, ahead of
+          // the conditional — the same carrier the single-return path uses. A
+          // JS-runtime adapter (and the browser under /* @client */) runs it
+          // verbatim.
+          preamble = preambleFromValueStatements(pre, ctx)
+
+          // A DSL adapter can't carry a loop-local `const` into a conditional
+          // branch template, so it would render the branches with the local
+          // undefined (silent divergence). Refuse instead — adapter-gated like
+          // the filter/sort sites: a JS-runtime target folds and runs it, a DSL
+          // target errors with the /* @client */ escape (which renders the map
+          // client-only, where the browser runs the preamble). Stage 2 of
+          // spec/callback-fidelity.md.
+          if (!isClientOnly && !(ctx.analyzer.acceptsCallbackBody?.('map') ?? false)) {
+            ctx.analyzer.errors.push(
+              createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN, loc, {
+                message:
+                  'A .map() callback body with a `const`/`let` preamble before its ' +
+                  'branches cannot be lowered to a template: the loop-local binding ' +
+                  'cannot be carried into a conditional branch on this backend.',
+                suggestion: {
+                  message: 'Add /* @client */ to evaluate this expression on the client only',
+                },
+              })
+            )
+          }
+        }
+      }
+
       // Block body: (item) => { const label = ...; return <div>{label}</div> }
-      const returnStmt = body.statements.find(
-        (s): s is ts.ReturnStatement => ts.isReturnStatement(s) && s.expression != null
-      )
+      const returnStmt = children.length === 0
+        ? body.statements.find(
+            (s): s is ts.ReturnStatement => ts.isReturnStatement(s) && s.expression != null
+          )
+        : undefined
       if (returnStmt && returnStmt.expression) {
         let returnExpr = returnStmt.expression
         while (ts.isParenthesizedExpression(returnExpr)) {
@@ -4047,42 +4252,202 @@ function transformMapCall(
             children = [transformed]
           }
         }
-        const preambleStmts: string[] = []
-        const templatePreambleStmts: string[] = []
-        const typedPreambleStmts: string[] = []
-        let hasTypeDiff = false
-        let hasTemplateDiff = false
+        // Stage 3 of spec/callback-fidelity.md — an arbitrary `.map()` body that
+        // *constructs* JSX in a statement before its `return` (the classic
+        // `const out = []; for (const c of it.cells) out.push(<td>{c}</td>);
+        // return <tr>{out}</tr>` array-builder) cannot be lowered to a template.
+        // The preamble collector below reconstructs each statement with
+        // `ctx.getJS`, which strips *types* but not JSX, so the raw `<td>{c}</td>`
+        // would splice verbatim into the emitted client bundle — invalid JS, a
+        // silent syntax-error leak with no diagnostic. Refuse loudly instead of
+        // leaking. (A later Stage-3 PR renders such bodies verbatim on JS
+        // runtimes; until then it is a build error on every backend.)
+        // Scan only statements the preamble collector below would reach — i.e.
+        // those *before* `returnStmt` (it `break`s at the return). JSX in
+        // unreachable post-return dead code is never spliced into the preamble,
+        // so it is not part of the leak and must not trip the refusal.
+        let jsxPreambleStmt: ts.Statement | undefined
         for (const stmt of body.statements) {
           if (stmt === returnStmt) break
-          const js = ctx.getJS(stmt)
-          const tjs = ctx.getTemplateJS(stmt)
-          const ts = stmt.getText(ctx.sourceFile)
-          preambleStmts.push(js.endsWith(';') ? js : js + ';')
-          templatePreambleStmts.push(tjs.endsWith(';') ? tjs : tjs + ';')
-          typedPreambleStmts.push(ts.endsWith(';') ? ts : ts + ';')
-          if (js !== ts) hasTypeDiff = true
-          if (js !== tjs) hasTemplateDiff = true
+          if (containsJsxInExpression(stmt)) {
+            jsxPreambleStmt = stmt
+            break
+          }
         }
-        if (preambleStmts.length > 0) {
-          mapPreamble = preambleStmts.join(' ')
-          if (hasTemplateDiff) {
-            templateMapPreamble = templatePreambleStmts.join(' ')
+        if (jsxPreambleStmt) {
+          // Stage 3 / D4 (spec/callback-fidelity.md). A JS-runtime adapter runs
+          // the callback body verbatim — each JSX leaf lowers to a template-
+          // literal HTML string, the imperative control flow runs as-is, and the
+          // element-array child ({out}) is joined into the row. A DSL template
+          // runtime can't do this, so it refuses with the /* @client */ escape
+          // (which renders the loop client-only, where the browser — always JS —
+          // runs the same body). Mirrors the const-preamble gate above and the
+          // Stage-1 filter/sort sites (all consult `acceptsCallbackBody`).
+          const jsRuntime = isClientOnly || (ctx.analyzer.acceptsCallbackBody?.('map') ?? false)
+          if (children.length === 0) {
+            // The return shape produced no loop children (a bare identifier
+            // `return out`, a ternary, any non-element return): there is no
+            // single template root to host the built elements, so the loop IR
+            // can't exist and the fallback would splice the raw callback —
+            // JSX included — verbatim into an expression anchor (a silent
+            // leak on EVERY tier, /* @client */ included). Refuse loudly with
+            // restructuring guidance; the return-shape holes pinned by
+            // map-body-no-silent-divergence.test.ts close here.
+            ctx.analyzer.errors.push(
+              createError(
+                ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+                getSourceLocation(jsxPreambleStmt, ctx.sourceFile, ctx.filePath),
+                {
+                  message:
+                    'A .map() callback that builds JSX in a statement before its ' +
+                    '`return` must return a single JSX element that embeds the ' +
+                    'built array — this return shape has no element root to host it.',
+                  suggestion: {
+                    message:
+                      'Wrap the result in one element root, e.g. `return <tr key={item.id}>{out}</tr>`.',
+                  },
+                }
+              )
+            )
+          } else if (!jsRuntime) {
+            ctx.analyzer.errors.push(
+              createError(
+                ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+                getSourceLocation(jsxPreambleStmt, ctx.sourceFile, ctx.filePath),
+                {
+                  message:
+                    'A .map() callback that builds JSX in a statement before its ' +
+                    '`return` (for example pushing elements into an array in a loop) ' +
+                    'cannot be lowered to a template on this backend.',
+                  suggestion: {
+                    message: 'Add /* @client */ to render this loop on the client only',
+                  },
+                }
+              )
+            )
+          } else {
+            const collected = buildPreambleSegments(body.statements, returnStmt, ctx)
+            if (collected.refusalNode) {
+              // A leaf carries wiring the verbatim path can't render (event
+              // handler, component, nested loop, reactive slot, spread), or
+              // sits inside a template literal (a segment boundary there would
+              // split the literal's lexical state for downstream text
+              // transforms). Refuse loudly (D-E) rather than emit a
+              // silently-degraded node.
+              ctx.analyzer.errors.push(
+                createError(
+                  ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+                  getSourceLocation(collected.refusalNode, ctx.sourceFile, ctx.filePath),
+                  {
+                    message:
+                      'A JSX element built in a .map() callback preamble cannot carry ' +
+                      'event handlers, components, nested loops, or reactive expressions, ' +
+                      'and cannot sit inside a template literal — the verbatim render ' +
+                      'path builds it once, with no reactive wiring.',
+                    suggestion: {
+                      message:
+                        'Return the element directly (not through a preamble variable), ' +
+                        'or add /* @client */ to render the loop on the client only.',
+                    },
+                  }
+                )
+              )
+            } else {
+              preamble = collected.preamble
+            }
           }
-          if (hasTypeDiff) {
-            typedMapPreamble = typedPreambleStmts.join(' ')
+        } else {
+          const valueStmts: ts.Statement[] = []
+          for (const stmt of body.statements) {
+            if (stmt === returnStmt) break
+            valueStmts.push(stmt)
+          }
+          if (valueStmts.length > 0) {
+            preamble = preambleFromValueStatements(valueStmts, ctx)
           }
         }
       }
 
       // flatMap block body fallback: compile JSX inline when children
-      // couldn't be extracted via the standard single-return path.
-      if (method === 'flatMap' && children.length === 0) {
+      // couldn't be extracted via the standard single-return path. A pure
+      // single-`return <call>` projection is NOT taken here — it lowers to
+      // neutral IR below (nested-loop child), which DSL adapters templatize.
+      if (method === 'flatMap' && children.length === 0 && !flatMapProjectionCall(body)) {
         flatMapCallback = buildFlatMapCallback(callback, body, ctx)
       }
     } else {
       tryTransformRenderableBody(body)
     }
 
+    // flatMap PROJECTION body — the canonical `flatMap(it => it.tags.map(tag
+    // => <li key={...}/>))`, as an expression body or a single-`return` block
+    // (parenthesized or not). This is a pure nested-loop projection, so it
+    // lowers to NEUTRAL IR — an inner IRLoop as the loop's only child — which
+    // every SSR adapter can templatize (nested `{{range}}` on DSL backends),
+    // per spec/callback-fidelity.md's fidelity table ("single expr" row) and
+    // the array-literal flatMap precedent. Only bodies carrying STATEMENTS
+    // (early returns, consts) fall through to the segments carrier below and
+    // its DSL gate. The client reconciles the flattened leaves through the
+    // descriptor mapArray path, synthesized from this same neutral IR
+    // (`renderFlatMapProjectionClientBody`); the leaf `key` renders as the
+    // usual nested-loop `data-key-1` on both the SSR and client string
+    // sides, and the flattened reconciliation identity (`data-key`) is
+    // stamped by mapArray from the inner loop's `key` field.
+    if (method === 'flatMap' && children.length === 0 && !flatMapCallback) {
+      const projection = flatMapProjectionCall(body)
+      if (projection) {
+        const transformed = transformJsxExpression(projection, ctx, isClientOnly)
+        if (transformed && transformed.type === 'loop') {
+          children = [transformed]
+        }
+      }
+    }
+
+    // flatMap EXPRESSION body containing JSX in a non-projection shape —
+    // e.g. a call wrapping JSX. The block-body form already rides the
+    // structured-segments carrier in the isBlock branch above; an unbraced
+    // body is the same shape minus the braces, so route it through the same
+    // door. Without this the dispatch falls to the IRExpression scalar path,
+    // which splices the raw callback — JSX included — verbatim into the
+    // client bundle: a silent SyntaxError that kills the whole component's
+    // hydration.
+    if (method === 'flatMap' && children.length === 0 && !flatMapCallback && !ts.isBlock(body)) {
+      flatMapCallback = buildFlatMapCallback(callback, body, ctx)
+    }
+
+    // A flatMapCallback carries the WHOLE body (statements included) as
+    // structured segments — the generic statements-before-return `preamble`
+    // the block-body path may have collected above is a duplicate carrier.
+    // Worse, it isn't one: spliced into a mapArray renderItem it re-runs the
+    // body's control flow against the wrong binding shape (the audited
+    // `if (t().tags.length > maxTags) return [];` renderItem residue).
+    // The segments carrier is the single door; drop the shadow copy.
+    if (flatMapCallback) preamble = undefined
+
+    // Adapter gate (spec/callback-fidelity.md fidelity model): a flatMap body
+    // carried as structured segments runs verbatim on a JS runtime; a DSL
+    // template runtime cannot execute it at SSR — pre-gate, e.g. the Go
+    // adapter emitted `{{range …}}{{end}}` with an EMPTY body (silent
+    // divergence, the exact failure class the sound-or-loud invariant
+    // forbids). Refuse loudly with the /* @client */ escape, mirroring the
+    // const-preamble and array-builder gates above.
+    if (flatMapCallback && !isClientOnly && !(ctx.analyzer.acceptsCallbackBody?.('flatMap') ?? false)) {
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          getSourceLocation(body, ctx.sourceFile, ctx.filePath),
+          {
+            message:
+              'A .flatMap() callback body with statements or a nested projection ' +
+              'cannot be lowered to a template on this backend.',
+            suggestion: {
+              message: 'Add /* @client */ to render this loop on the client only',
+            },
+          }
+        )
+      )
+    }
+
     // Unregister loop params
     if (paramBindings) {
       for (const b of paramBindings) ctx.loopParams.delete(b.name)
@@ -4097,6 +4462,43 @@ function transformMapCall(
   // fall back to treating the entire expression as an IRExpression — unless
   // flatMap already built a compiled callback (flatMapCallback).
   if (children.length === 0 && !flatMapCallback) {
+    // Structural net (sound-or-loud, spec/callback-fidelity.md): a callback
+    // body that carries an INLINE JSX literal but produced no loop lowering
+    // must never fall through to the IRExpression scalar path — `ctx.getJS`
+    // strips types, not JSX, so the raw `<li …>` would splice verbatim into
+    // the emitted client bundle as a silent SyntaxError. Any recognizer gap
+    // for a JSX-bearing shape becomes a loud diagnostic here instead of a
+    // leak. (A JSX-helper CALL — `map(t => renderItem(t))` — carries no
+    // inline JSX literal and legitimately stays on the reactive-text path.)
+    const cb = node.arguments[0]
+    const cbBody = cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb)) ? cb.body : undefined
+    // Entry-count gate: a more specific refusal already fired for THIS call
+    // (e.g. the flatMap leaf-wiring check) — don't stack the generic message
+    // on top of it. Comparing against the count captured at entry (not
+    // `=== 0`) keeps the net armed when an unrelated diagnostic was recorded
+    // earlier in the file — a warning elsewhere must never silence the leak
+    // guard for this callback.
+    if (cbBody && containsJsxInExpression(cbBody) && ctx.analyzer.errors.length === diagCountAtEntry) {
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          getSourceLocation(cbBody, ctx.sourceFile, ctx.filePath),
+          {
+            message:
+              `A .${method}() callback that builds JSX in this shape cannot be ` +
+              'compiled — the JSX would leak verbatim into the client bundle. ' +
+              'Recognized bodies: a JSX element/fragment, a ternary or ' +
+              '&& / || / ?? expression, an array literal (flatMap), or a block ' +
+              'body whose return the compiler can lower.',
+            suggestion: {
+              message:
+                'Restructure the callback to return the JSX element directly ' +
+                '(or via a block body with a plain `return`).',
+            },
+          }
+        )
+      )
+    }
     return null
   }
 
@@ -4122,6 +4524,70 @@ function transformMapCall(
     ? extractItemConditionalKey(itemConditional!)
     : (children.length > 0 ? extractLoopKey(children[0]) : null)
 
+  // Stage 3 / D5 (spec/callback-fidelity.md) — the keyFn is hoisted: `mapArray`
+  // computes it from the raw item BEFORE the callback body runs, so the key must
+  // be derivable from the item (and index), never from a value the preamble
+  // computes. A key that reads a preamble-declared local would compile to an
+  // unbound keyFn; refuse instead.
+  const declaredNameSet = preamble && preamble.declaredNames.length > 0
+    ? new Set(preamble.declaredNames)
+    : undefined
+  if (key && declaredNameSet) {
+    const keyRefs = extractFreeIdentifiersFromText(key)
+    const usesLocal = [...keyRefs].some((r) => declaredNameSet.has(r))
+    if (usesLocal) {
+      ctx.analyzer.errors.push(
+        createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN, getSourceLocation(node, ctx.sourceFile, ctx.filePath), {
+          message:
+            'A .map() loop key must be derivable from the loop item — it is ' +
+            'evaluated before the callback body runs, so it cannot reference a ' +
+            'value computed in the callback preamble.',
+          suggestion: {
+            message: 'Derive the key directly from the loop item (e.g. key={item.id}).',
+          },
+        })
+      )
+    }
+  }
+
+  // Stage 3 / D4 — flag element-array children ({out}) built by the preamble so
+  // Phase-2 string emission joins them instead of `String([])`-collapsing them.
+  // Scoped to builderNames (leaf accumulators), NOT all declared locals — a
+  // value-only `{label}` keeps its historical plain interpolation.
+  if (preamble && preamble.builderNames.length > 0) {
+    flagArrayChildExpressions(children, new Set(preamble.builderNames))
+  }
+
+  // Stage 3 root cure — a JSX-building preamble feeding a COMPONENT root is
+  // refused: the component loop's rows are createComponent-driven ('dom-ops'
+  // row construction), and a lowered HTML-string leaf passed as a prop would
+  // silently diverge from SSR, where the same prop is a real JSX element.
+  if (
+    preamble &&
+    preamble.builderNames.length > 0 &&
+    children.length === 1 &&
+    children[0].type === 'component'
+  ) {
+    ctx.analyzer.errors.push(
+      createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN, getSourceLocation(node, ctx.sourceFile, ctx.filePath), {
+        message:
+          'A .map() callback that builds JSX in its preamble cannot return a ' +
+          'component: the built elements would reach the component as raw HTML ' +
+          'strings on the client but as JSX elements at SSR (a silent divergence).',
+        suggestion: {
+          message:
+            'Return a plain element root that embeds the array, or move the ' +
+            'building logic inside the component.',
+        },
+      })
+    )
+    // Refused = not carried (the old "do NOT collect" principle): codegen
+    // still runs on an errored compile, and the dom-ops backstop invariant
+    // must stay a FUTURE-variant tripwire, not re-fire on shapes Phase 1
+    // already refused loudly.
+    preamble = undefined
+  }
+
   // Extract childComponent info if the loop body is a single component
   // This enables createComponent-based rendering with proper prop passing
   let childComponent: IRLoopChildComponent | undefined
@@ -4181,6 +4647,17 @@ function transformMapCall(
     // already handles correctly.
     && !objectIteration
 
+  // #2389 patch-on-update — a signal-backed (non-static) loop whose body has
+  // a preamble may reference a preamble-declared local directly as a child
+  // expression (`{cells}`, `{stateLabel}`). `mapArray` reuses the same DOM
+  // node on a same-key update, re-running only the wired text/attr slots —
+  // this child has neither, so without a dedicated region-patch effect it
+  // freezes at its mount-time value. Static arrays are never recreated via
+  // signals, so there is nothing to patch; skip them entirely.
+  const preambleRegions = preamble && !isStaticArray
+    ? collectPreambleRegions(children, new Set(preamble.declaredNames), ctx)
+    : undefined
+
   // Collect nested components for both static and dynamic arrays.
   // Static arrays: needed for initChild hydration.
   // Dynamic arrays with native root + component descendants: enables reconcileElements
@@ -4222,11 +4699,10 @@ function transformMapCall(
     objectIteration,
     depth,
     clientOnly: isClientOnly || undefined,
-    mapPreamble,
-    templateMapPreamble,
+    preamble,
+    preambleRegions: preambleRegions && preambleRegions.length > 0 ? preambleRegions : undefined,
     paramType,
     indexType,
-    typedMapPreamble,
     paramBindings,
     arrayFreeIdentifiers: extractFreeIdentifiersFromNode(arrayExpr),
     flatMapCallback,
@@ -4269,67 +4745,483 @@ function containsJsx(node: ts.Node): boolean {
 }
 
 /**
- * Build a FlatMapCallback for complex flatMap block bodies (conditional
- * returns, variable-assigned JSX, etc.). Walks the callback body AST,
- * transforms each JSX node to IR, replaces it with a `__BF_JSX_N__`
- * placeholder, and returns the compiled callback descriptor.
+ * Build a FlatMapCallback for complex flatMap bodies (conditional returns,
+ * variable-assigned JSX, etc.). Accepts a block body OR an expression body
+ * (`t => t.tags.map(tag => <li/>)`) — segment reconstruction and the SSR
+ * rawBody are position-based, so both shapes flow through identically (a
+ * block's text keeps its braces; an expression's text is a valid arrow body
+ * as-is). Walks the callback body AST and carries it as structured segments
+ * — JS text (types stripped) interleaved with compiled JSX-leaf IR — never
+ * as a sentinel-bearing string (the write-side rule in CLAUDE.md; same shape
+ * as the map-preamble carrier).
  */
 function buildFlatMapCallback(
   callback: ts.ArrowFunction | ts.FunctionExpression,
-  body: ts.Block,
+  body: ts.Block | ts.Expression,
   ctx: TransformContext,
 ): FlatMapCallback | undefined {
   if (!containsJsx(body)) return undefined
 
-  const fragments: FlatMapJsxFragment[] = []
-  const sourceText = ctx.sourceFile.text
-  const bodyStart = body.getStart(ctx.sourceFile)
-  const bodyEnd = body.getEnd()
-  const bodyText = sourceText.slice(bodyStart, bodyEnd)
-
-  // Collect all JSX nodes and their positions, sorted by start position
-  const jsxNodes: Array<{ node: ts.Node; start: number; end: number }> = []
-  function collectJsx(n: ts.Node): void {
+  // Collect all JSX leaves — don't descend into a JSX node (transformNode
+  // compiles its interior). A leaf under a template literal is refused (a
+  // segment boundary there would split the literal's lexical state), same as
+  // the map-preamble collector.
+  const leafSpans: Array<{ start: number; end: number }> = []
+  const leafIrs: IRNode[] = []
+  let refusalNode: ts.Node | undefined
+  const collectJsx = (n: ts.Node, underTemplate: boolean): void => {
     if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n)) {
-      jsxNodes.push({
-        node: n,
-        start: n.getStart(ctx.sourceFile) - bodyStart,
-        end: n.getEnd() - bodyStart,
-      })
+      if (underTemplate) refusalNode ??= n
+      leafSpans.push({ start: n.getStart(ctx.sourceFile), end: n.getEnd() })
+      const ir = transformNode(n as ts.Expression, ctx)
+      leafIrs.push(ir ?? { type: 'text', value: '', loc: getSourceLocation(n, ctx.sourceFile, ctx.filePath) })
       return
     }
-    n.forEachChild(collectJsx)
+    const inTemplate = underTemplate || ts.isTemplateExpression(n) || ts.isTaggedTemplateExpression(n)
+    n.forEachChild((c) => collectJsx(c, inTemplate))
   }
-  collectJsx(body)
-
-  if (jsxNodes.length === 0) return undefined
+  collectJsx(body, false)
 
-  // Build the body text with JSX replaced by placeholders
-  let compiledBody = ''
-  let lastEnd = 0
-  for (let i = 0; i < jsxNodes.length; i++) {
-    const { node, start, end } = jsxNodes[i]
-    const placeholder = `__BF_JSX_${i}__`
-    compiledBody += bodyText.slice(lastEnd, start) + placeholder
-    lastEnd = end
+  if (leafSpans.length === 0) return undefined
+  if (refusalNode) {
+    ctx.analyzer.errors.push(
+      createError(
+        ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+        getSourceLocation(refusalNode, ctx.sourceFile, ctx.filePath),
+        {
+          message:
+            'A JSX element inside a template literal in a .flatMap() callback ' +
+            'body cannot be compiled.',
+          suggestion: { message: 'Build the element outside the template literal.' },
+        }
+      )
+    )
+    return undefined
+  }
 
-    const ir = transformNode(node as any, ctx)
-    fragments.push({
-      placeholder,
-      ir: ir ?? { type: 'text', value: '', loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath) },
-    })
+  // A leaf that carries wiring the descriptor render path can't honour —
+  // an event handler, a component, a nested loop, or a spread — would be
+  // silently dead DOM on the client (the leaf renders as a keyed HTML
+  // string, patched wholesale on change, with no per-slot wiring). Refuse
+  // loudly (sound-or-loud), mirroring `preambleFragmentNeedsWiring` for map
+  // preambles — but deliberately NOT refusing reactive expressions: whole-
+  // leaf patching covers those.
+  for (const leafIr of leafIrs) {
+    // The descriptor path renders each leaf as ONE keyed element — the
+    // renderItem adopts `template.content.firstElementChild` and `patchLeaf`
+    // patches a single element root. A fragment (or any non-element) root
+    // would silently drop siblings client-side while SSR renders them all —
+    // the exact divergence class this carrier forbids. Refuse loudly.
+    if (leafIr.type !== 'element') {
+      const loc = 'loc' in leafIr && leafIr.loc
+        ? leafIr.loc
+        : getSourceLocation(body, ctx.sourceFile, ctx.filePath)
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          loc,
+          {
+            message:
+              'A JSX leaf produced by a .flatMap() callback must be a single ' +
+              'element — a fragment or non-element root cannot ride the keyed ' +
+              'descriptor path (each leaf hydrates and patches as one element).',
+            suggestion: {
+              message: 'Wrap the leaf content in a single keyed element.',
+            },
+          }
+        )
+      )
+      return undefined
+    }
+    if (flatMapLeafNeedsWiring(leafIr)) {
+      const loc = 'loc' in leafIr && leafIr.loc
+        ? leafIr.loc
+        : getSourceLocation(body, ctx.sourceFile, ctx.filePath)
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          loc,
+          {
+            message:
+              'A JSX element produced by a .flatMap() callback cannot carry ' +
+              'event handlers, components, nested loops, or spreads — the ' +
+              'leaf renders as a keyed HTML string with no per-element wiring.',
+            suggestion: {
+              message:
+                'Restructure so the interactive element lives in a .map() body — ' +
+                'the descriptor path has no per-element wiring on any backend, ' +
+                'so /* @client */ does not lift this.',
+            },
+          }
+        )
+      )
+      return undefined
+    }
   }
-  compiledBody += bodyText.slice(lastEnd)
 
-  // Build the template body (with prop refs rewritten)
+  const pieces = reconstructAsSegments(body, ctx.sourceFile, ctx.analyzer.typeExcludeRanges, leafSpans)
+  const segments: PreambleSegment[] = pieces.map((piece) => {
+    if ('marker' in piece) return { kind: 'jsx', ir: leafIrs[piece.marker] }
+    // Template variant per segment, like buildPreambleSegments: the hydrate
+    // registration template is module scope (`template: (_p) => ...`), so a
+    // bare destructured-prop reference must rewrite to `_p.xxx` there —
+    // `applyPropsRewrite` can't do it (destructured components have no props
+    // object name).
+    const tpl = rewriteBarePropRefs(piece.js, body, ctx)
+    return tpl !== undefined && tpl !== piece.js
+      ? { kind: 'js', text: piece.js, templateText: tpl }
+      : { kind: 'js', text: piece.js }
+  })
+
   const paramsText = callback.parameters.map(p => p.getText(ctx.sourceFile)).join(', ')
 
   return {
     params: `(${paramsText})`,
-    body: compiledBody,
-    templateBody: compiledBody,
-    rawBody: bodyText,
-    fragments,
+    segments,
+    rawBody: tsxSourceText(body.getText(ctx.sourceFile)),
+  }
+}
+
+/**
+ * Stage 3 / D4 (spec/callback-fidelity.md) — the collected JSX-bearing preamble
+ * of an arbitrary `.map()` callback (an imperative array-builder), structured.
+ */
+interface PreambleCollection {
+  preamble: MapCallbackPreamble
+  /** Set when a leaf carries wiring the verbatim path can't render (D-E). */
+  refusalNode?: ts.Node
+}
+
+/**
+ * Does a flatMap segment leaf carry wiring the descriptor render path can't
+ * honour? Narrower than {@link preambleFragmentNeedsWiring}: reactive
+ * expressions are ALLOWED (the client renders each leaf as a keyed
+ * `{ k, h }` descriptor and patches the whole leaf when its HTML changes),
+ * but events, components, nested loops, and spreads have no wiring on that
+ * path and would be silently dead.
+ */
+function flatMapLeafNeedsWiring(ir: IRNode): boolean {
+  switch (ir.type) {
+    case 'component':
+    case 'loop':
+      return true
+    case 'element':
+      if (ir.events.length > 0) return true
+      if (ir.attrs.some((a) => a.name.startsWith('...'))) return true
+      return ir.children.some(flatMapLeafNeedsWiring)
+    case 'conditional':
+      return (
+        flatMapLeafNeedsWiring(ir.whenTrue) ||
+        (ir.whenFalse ? flatMapLeafNeedsWiring(ir.whenFalse) : false)
+      )
+    case 'fragment':
+      return ir.children.some(flatMapLeafNeedsWiring)
+    default:
+      return false
+  }
+}
+
+/**
+ * Does a compiled preamble JSX leaf carry wiring the verbatim render path can't
+ * honour? The path builds each leaf once as an interpolated HTML string with no
+ * reactive effects, event listeners, or child reconciliation — so an event
+ * handler, a component, a nested loop, a reactive slot, or a spread would be
+ * silently dropped. Refuse instead (D-E), never diverge silently.
+ */
+function preambleFragmentNeedsWiring(ir: IRNode): boolean {
+  switch (ir.type) {
+    case 'component':
+    case 'loop':
+      return true
+    case 'element':
+      if (ir.events.length > 0) return true
+      // JSX spread (`<x {...rest} />`) keeps `name === '...'` as its marker.
+      if (ir.attrs.some((a) => a.name.startsWith('...'))) return true
+      return ir.children.some(preambleFragmentNeedsWiring)
+    case 'expression':
+      return ir.reactive === true
+    case 'conditional':
+      return (
+        preambleFragmentNeedsWiring(ir.whenTrue) ||
+        (ir.whenFalse ? preambleFragmentNeedsWiring(ir.whenFalse) : false)
+      )
+    case 'fragment':
+      return ir.children.some(preambleFragmentNeedsWiring)
+    default:
+      return false
+  }
+}
+
+/**
+ * Stage 3 / D4 — walk loop-body children and flag each `IRExpression` child
+ * whose free identifiers intersect the preamble-declared names (e.g. `{out}`).
+ * Phase-2 string emission then joins the array instead of `String([])`-collapsing
+ * it. JSX SSR adapters ignore the flag (their JSX runtime renders arrays).
+ */
+function flagArrayChildExpressions(nodes: IRNode[], declared: ReadonlySet<string>): void {
+  for (const node of nodes) {
+    switch (node.type) {
+      case 'expression': {
+        // Only the bare `{out}` shape — the whole expression is a single
+        // identifier that is itself a preamble-declared array. A broader
+        // expression (`{out.length}`, `{f(out)}`) must NOT get the array-join
+        // coercion: it would change the value, and the join ternary reads the
+        // expression twice, so a call could double-fire its side effects.
+        const name = node.expr.trim()
+        const refs = extractFreeIdentifiersFromText(node.expr)
+        if (refs.size === 1 && refs.has(name) && declared.has(name)) {
+          node.joinArrayChild = true
+        }
+        break
+      }
+      case 'element':
+      case 'fragment':
+        flagArrayChildExpressions(node.children, declared)
+        break
+      case 'conditional':
+        flagArrayChildExpressions(
+          [node.whenTrue, ...(node.whenFalse ? [node.whenFalse] : [])],
+          declared,
+        )
+        break
+    }
+  }
+}
+
+/**
+ * #2389 patch-on-update — walk loop-body children and classify each
+ * `IRExpression` whose free identifiers intersect `declared` (the enclosing
+ * `.map()` preamble's `declaredNames`) as a preamble-patched region. Unlike
+ * {@link flagArrayChildExpressions} (which only recognizes the exact bare
+ * `{out}` shape for the array-join coercion), this is deliberately broader —
+ * ANY expression reading a preamble local needs the region-patch effect,
+ * whether it's a builder array (`{cells}`, `joinArrayChild` already set by
+ * `flagArrayChildExpressions`, called earlier for the same `children`) or a
+ * plain value (`{stateLabel}`).
+ *
+ * Reuses an existing `slotId` when the node already has one (e.g. it also
+ * reads the loop param and so already qualified via the ordinary reactive-
+ * text path) rather than allocating a second slot — `node.preambleRegion`
+ * is the single source of truth downstream, so `collectLoopChildReactiveTexts`
+ * can unconditionally defer to it.
+ */
+function collectPreambleRegions(
+  nodes: IRNode[],
+  declared: ReadonlySet<string>,
+  ctx: TransformContext,
+): PreambleRegionSource[] {
+  const regions: PreambleRegionSource[] = []
+  const visit = (list: IRNode[]): void => {
+    for (const node of list) {
+      switch (node.type) {
+        case 'expression': {
+          const refs = extractFreeIdentifiersFromText(node.expr)
+          const usesPreambleLocal = [...refs].some((r) => declared.has(r))
+          if (usesPreambleLocal) {
+            if (!node.slotId) node.slotId = generateSlotId(ctx)
+            node.preambleRegion = true
+            node.reactive = true
+            regions.push({
+              slotId: node.slotId,
+              expr: node.expr,
+              joinArrayChild: node.joinArrayChild || undefined,
+            })
+          }
+          break
+        }
+        case 'element':
+        case 'fragment':
+          visit(node.children)
+          break
+        case 'conditional':
+          visit([node.whenTrue, ...(node.whenFalse ? [node.whenFalse] : [])])
+          break
+      }
+    }
+  }
+  visit(nodes)
+  return regions
+}
+
+/**
+ * Collect the names a binding introduces, recursing through object/array
+ * destructuring patterns (`const { id: k } = r`, `const [k, ...rest] = xs`) so
+ * the D5 key-derivability guard sees every preamble-scoped local — mirrors
+ * `collectParamBindingNames`.
+ */
+function collectBindingNames(name: ts.BindingName, out: Set<string>): void {
+  if (ts.isIdentifier(name)) {
+    out.add(name.text)
+    return
+  }
+  // Object / array binding pattern; array holes are OmittedExpression, skipped.
+  for (const el of name.elements) {
+    if (ts.isBindingElement(el)) collectBindingNames(el.name, out)
+  }
+}
+
+/** Names a preamble statement declares (const/let/var/function). */
+function collectPreambleDeclaredNames(stmt: ts.Statement, out: Set<string>): void {
+  if (ts.isVariableStatement(stmt)) {
+    for (const decl of stmt.declarationList.declarations) {
+      collectBindingNames(decl.name, out)
+    }
+  } else if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+    out.add(stmt.name.text)
+  }
+}
+
+/**
+ * Build a {@link MapCallbackPreamble} from value-only (JSX-free) pre-return
+ * statements — the Stage-2 fold preamble and the plain block-body preamble.
+ * One `js` segment per statement, semicolon-normalized and space-joined
+ * exactly as the former string carriers were.
+ */
+function preambleFromValueStatements(
+  statements: readonly ts.Statement[],
+  ctx: TransformContext,
+): MapCallbackPreamble {
+  const segments: PreambleSegment[] = []
+  const typedParts: string[] = []
+  const declared = new Set<string>()
+  for (const stmt of statements) {
+    collectPreambleDeclaredNames(stmt, declared)
+    const js0 = ctx.getJS(stmt)
+    const tjs0 = ctx.getTemplateJS(stmt)
+    const raw0 = stmt.getText(ctx.sourceFile)
+    const js = (js0.endsWith(';') ? js0 : js0 + ';') + ' '
+    const tjs = (tjs0.endsWith(';') ? tjs0 : tjs0 + ';') + ' '
+    typedParts.push(raw0.endsWith(';') ? raw0 : raw0 + ';')
+    segments.push(tjs !== js ? { kind: 'js', text: js, templateText: tjs } : { kind: 'js', text: js })
+  }
+  return {
+    segments: trimPreambleSegments(segments),
+    ssrText: tsxSourceText(typedParts.join(' ')),
+    declaredNames: [...declared],
+    // Value-only preambles accumulate no JSX, so no child needs the array join.
+    builderNames: [],
+  }
+}
+
+/** Drop the trailing separator space from the final js segment. */
+function trimPreambleSegments(segments: PreambleSegment[]): PreambleSegment[] {
+  const last = segments[segments.length - 1]
+  if (last?.kind === 'js') {
+    const text = last.text.trimEnd()
+    const templateText = last.templateText?.trimEnd()
+    segments[segments.length - 1] = templateText !== undefined
+      ? { kind: 'js', text, templateText }
+      : { kind: 'js', text }
+  }
+  return segments
+}
+
+/**
+ * Collect an arbitrary `.map()` callback's pre-return statements as structured
+ * segments: JS text between JSX leaves becomes `js` segments (types stripped via
+ * the same span-walk as `reconstructWithoutTypes`), each top-level JSX leaf
+ * becomes a `jsx` segment carrying its compiled IR. No sentinel string ever
+ * exists. Each leaf is checked against {@link preambleFragmentNeedsWiring}; a
+ * leaf inside a template literal is refused (a segment boundary there would
+ * split the literal's lexical state for downstream per-segment text
+ * transforms).
+ */
+function buildPreambleSegments(
+  statements: ts.NodeArray<ts.Statement>,
+  returnStmt: ts.Statement | undefined,
+  ctx: TransformContext,
+): PreambleCollection {
+  const segments: PreambleSegment[] = []
+  const typedParts: string[] = []
+  const declared = new Set<string>()
+  const builders = new Set<string>()
+  let refusalNode: ts.Node | undefined
+
+  // Which local does this leaf accumulate into? The `push`/`unshift` receiver
+  // (`out.push(<td/>)`) or the declaration target of a leaf-bearing
+  // initializer (`const out = xs.map(x => <td/>)`). Only these names get the
+  // `{out}` array-join child emission — a value-only local must keep its
+  // plain interpolation (pinned by client-js-generation.test.ts #520).
+  const recordBuilderTarget = (leaf: ts.Node, stmt: ts.Statement): void => {
+    for (let n: ts.Node | undefined = leaf.parent; n && n !== stmt.parent; n = n.parent) {
+      if (
+        ts.isCallExpression(n) &&
+        ts.isPropertyAccessExpression(n.expression) &&
+        (n.expression.name.text === 'push' || n.expression.name.text === 'unshift') &&
+        ts.isIdentifier(n.expression.expression)
+      ) {
+        builders.add(n.expression.expression.text)
+        return
+      }
+      if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name)) {
+        builders.add(n.name.text)
+        return
+      }
+    }
+  }
+
+  for (const stmt of statements) {
+    if (stmt === returnStmt) break
+    collectPreambleDeclaredNames(stmt, declared)
+
+    // Top-level JSX leaves in this statement — don't descend into a JSX node
+    // (transformNode compiles its interior). Mirrors buildFlatMapCallback.
+    const leafSpans: Array<{ start: number; end: number }> = []
+    const leafIrs: IRNode[] = []
+    const collect = (n: ts.Node, underTemplate: boolean): void => {
+      if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n)) {
+        if (underTemplate) refusalNode ??= n
+        recordBuilderTarget(n, stmt)
+        leafSpans.push({ start: n.getStart(ctx.sourceFile), end: n.getEnd() })
+        const ir = transformNode(n as ts.Expression, ctx)
+        if (ir && preambleFragmentNeedsWiring(ir)) refusalNode ??= n
+        leafIrs.push(ir ?? { type: 'text', value: '', loc: getSourceLocation(n, ctx.sourceFile, ctx.filePath) })
+        return
+      }
+      const inTemplate = underTemplate || ts.isTemplateExpression(n) || ts.isTaggedTemplateExpression(n)
+      n.forEachChild((c) => collect(c, inTemplate))
+    }
+    collect(stmt, false)
+
+    const raw0 = stmt.getText(ctx.sourceFile)
+    typedParts.push(raw0.endsWith(';') ? raw0 : raw0 + ';')
+
+    if (leafSpans.length === 0) {
+      const js0 = ctx.getJS(stmt)
+      const tjs0 = ctx.getTemplateJS(stmt)
+      const js = (js0.endsWith(';') ? js0 : js0 + ';') + ' '
+      const tjs = (tjs0.endsWith(';') ? tjs0 : tjs0 + ';') + ' '
+      segments.push(tjs !== js ? { kind: 'js', text: js, templateText: tjs } : { kind: 'js', text: js })
+      continue
+    }
+
+    const pieces = reconstructAsSegments(stmt, ctx.sourceFile, ctx.analyzer.typeExcludeRanges, leafSpans)
+    for (const piece of pieces) {
+      if ('marker' in piece) {
+        segments.push({ kind: 'jsx', ir: leafIrs[piece.marker] })
+      } else {
+        // Per-segment template variant: the destructured-prop rewrite is a text
+        // transform; leaf refusal above guarantees segment boundaries never
+        // split a string/template literal's lexical state.
+        const tpl = rewriteBarePropRefs(piece.js, stmt, ctx)
+        segments.push(tpl !== undefined && tpl !== piece.js
+          ? { kind: 'js', text: piece.js, templateText: tpl }
+          : { kind: 'js', text: piece.js })
+      }
+    }
+    // Statement separator + semicolon normalization (the raw text may omit `;`).
+    const sep = raw0.endsWith(';') ? ' ' : '; '
+    segments.push({ kind: 'js', text: sep })
+  }
+
+  return {
+    preamble: {
+      segments: trimPreambleSegments(segments),
+      ssrText: tsxSourceText(typedParts.join(' ')),
+      declaredNames: [...declared],
+      builderNames: [...builders],
+    },
+    refusalNode,
   }
 }