@barefootjs/jsx 0.26.1 → 0.26.3

package/src/jsx-to-ir.ts

@@ -26,7 +26,9 @@ import {
   type LoopBindingPathSegment,
   type RestExcludeKey,
   type FlatMapCallback,
-  type FlatMapJsxFragment,
+  type MapCallbackPreamble,
+  type PreambleSegment,
+  tsxSourceText,
   type SourceLocation,
   type TypeInfo,
   type OriginInfo,
@@ -48,11 +50,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 +913,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 +2127,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(
@@ -3705,9 +3745,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 +3802,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 +3830,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 +3868,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 +3895,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 +4091,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,29 +4154,118 @@ 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
+            }
+          }
+        } else {
+          const valueStmts: ts.Statement[] = []
+          for (const stmt of body.statements) {
+            if (stmt === returnStmt) break
+            valueStmts.push(stmt)
           }
-          if (hasTypeDiff) {
-            typedMapPreamble = typedPreambleStmts.join(' ')
+          if (valueStmts.length > 0) {
+            preamble = preambleFromValueStatements(valueStmts, ctx)
           }
         }
       }
@@ -4122,6 +4318,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
@@ -4222,11 +4482,9 @@ function transformMapCall(
     objectIteration,
     depth,
     clientOnly: isClientOnly || undefined,
-    mapPreamble,
-    templateMapPreamble,
+    preamble,
     paramType,
     indexType,
-    typedMapPreamble,
     paramBindings,
     arrayFreeIdentifiers: extractFreeIdentifiersFromNode(arrayExpr),
     flatMapCallback,
@@ -4270,9 +4528,10 @@ 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.
+ * returns, variable-assigned JSX, etc.). 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,
@@ -4281,55 +4540,322 @@ function buildFlatMapCallback(
 ): 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
-
-    const ir = transformNode(node as any, ctx)
-    fragments.push({
-      placeholder,
-      ir: ir ?? { type: 'text', value: '', loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath) },
-    })
+  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
   }
-  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 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
+    }
+  }
+}
+
+/**
+ * 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,
   }
 }