@barefootjs/jsx 0.26.2 → 0.26.4

package/src/analyzer.ts

@@ -9,6 +9,7 @@
 import ts from 'typescript'
 import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, FactoryRenameSite, SourceLocation } from './types.ts'
 import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr } from './expression-parser.ts'
+import type { CallbackBodyAcceptor } from './adapters/interface.ts'
 import { rewriteBarePropRefs } from './prop-rewrite.ts'
 import { incrementCounter } from './instrumentation.ts'
 import {
@@ -158,7 +159,8 @@ export function analyzeComponent(
   source: string,
   filePath: string,
   targetComponentName?: string,
-  program?: ts.Program
+  program?: ts.Program,
+  acceptsCallbackBody?: CallbackBodyAcceptor
 ): AnalyzerContext {
   incrementCounter('filesAnalyzed')
   // Track whether the caller supplied a shared ts.Program. Used downstream
@@ -229,7 +231,7 @@ export function analyzeComponent(
     }
   }
 
-  const ctx = createAnalyzerContext(sourceFile, filePath)
+  const ctx = createAnalyzerContext(sourceFile, filePath, acceptsCallbackBody)
   ctx.checker = checker
 
   // Reactive-factory prescan results (#931, #2325 cross-file + object-
@@ -2077,18 +2079,77 @@ function extractSingleJsxReturn(
   return jsxReturn
 }
 
-type JsxReturnNode = ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment
+export type JsxReturnNode = ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment
+
+/**
+ * The branch structure extracted from a multi-return JSX body — an if/else-if
+ * chain or a `switch`. Shared by the helper-function fold and (Stage 2 of
+ * `spec/callback-fidelity.md`) the `.map()` callback-body fold.
+ */
+export interface MultiReturnJsxBranches {
+  branches: Array<{
+    condition: ts.Expression
+    jsxReturn: JsxReturnNode | null
+    /**
+     * For a `switch` with fallthrough (`case 'a': case 'b': return X`), the
+     * additional case expressions that share this branch's return. The fold
+     * OR-joins them with `condition` into `disc === a || disc === b`. Only set
+     * on switch-sourced branches.
+     */
+    extraCaseConditions?: ts.Expression[]
+  }>
+  fallback: JsxReturnNode | null
+  switchDiscriminant?: ts.Expression
+  /**
+   * Leading `const` / `let` declarations before the branches, collected only
+   * when the caller passes `allowPreamble` (the `.map()` body fold — Stage 2 of
+   * `spec/callback-fidelity.md`). A JS-runtime adapter folds them into a
+   * per-iteration preamble; a DSL adapter can't carry a loop-local into a
+   * conditional branch template, so the `.map()` lowering refuses (BF021 +
+   * `/* @client *\/`) rather than render wrong output. Empty for the
+   * helper-function inliner, which passes no `allowPreamble` and still bails on
+   * any variable statement.
+   */
+  preamble?: ts.VariableStatement[]
+}
+
+/**
+ * A leading-`const` preamble is only safe to fold when every branch (and the
+ * fallback) returns real JSX. If any returns `null`, the loop item can be null
+ * and the compiler routes the loop through the anchored conditional-item
+ * runtime (`mapArrayAnchored`), where a preamble local computed before the
+ * conditional interacts badly with the per-item hydration anchor — observed as
+ * a keyed-reactivity break on a real component (the pivot-table demo, whose
+ * `.map()` body is `const f = …; if (!f) return null; return <div key={fid}>`
+ * and which carries a workaround note about exactly this compiler behavior).
+ * When unsafe, bail so the body falls through to the single-return path
+ * unchanged. Stage 2 of `spec/callback-fidelity.md`.
+ */
+function preambleUnsafe(
+  preamble: ts.VariableStatement[],
+  branches: Array<{ jsxReturn: JsxReturnNode | null }>,
+  fallback: JsxReturnNode | null,
+): boolean {
+  if (preamble.length === 0) return false
+  return fallback === null || branches.some(b => b.jsxReturn === null)
+}
 
 /**
  * Extract conditional branches from a multi-return JSX helper function body.
  * Supports if/else if chains and switch statements where every branch
  * returns JSX or null. Returns null for unsupported patterns.
  */
-function extractMultiReturnJsxBranches(
-  body: ts.Block
-): { branches: Array<{ condition: ts.Expression; jsxReturn: JsxReturnNode | null }>; fallback: JsxReturnNode | null; switchDiscriminant?: ts.Expression } | null {
-  const branches: Array<{ condition: ts.Expression; jsxReturn: JsxReturnNode | null }> = []
+export function extractMultiReturnJsxBranches(
+  body: ts.Block,
+  allowPreamble = false,
+): MultiReturnJsxBranches | null {
+  const branches: Array<{
+    condition: ts.Expression
+    jsxReturn: JsxReturnNode | null
+    extraCaseConditions?: ts.Expression[]
+  }> = []
   let fallback: JsxReturnNode | null = null
+  const preamble: ts.VariableStatement[] = []
 
   const stmts = body.statements
   for (let i = 0; i < stmts.length; i++) {
@@ -2125,7 +2186,8 @@ function extractMultiReturnJsxBranches(
             return null
           }
           if (branches.length === 0) return null
-          return { branches, fallback }
+          if (preambleUnsafe(preamble, branches, fallback)) return null
+          return { branches, fallback, preamble }
         }
         break
       }
@@ -2151,23 +2213,49 @@ function extractMultiReturnJsxBranches(
       const hasDefault = stmt.caseBlock.clauses.some(c => ts.isDefaultClause(c))
       if (!hasDefault) return null
 
+      // Case labels that fall through to the next clause's body — an empty
+      // `case 'a':` immediately before `case 'b': return X` — share that
+      // return. Accumulate their expressions and attach them to the branch of
+      // the clause that finally carries the body. Stage 2 of
+      // spec/callback-fidelity.md.
+      let pendingCases: ts.Expression[] = []
       for (const clause of stmt.caseBlock.clauses) {
+        if (ts.isCaseClause(clause) && clause.statements.length === 0) {
+          pendingCases.push(clause.expression)
+          continue
+        }
+
         const jsxReturn = findJsxReturnInCaseClause(clause)
         const nullReturn = findNullReturnInCaseClause(clause)
         if (!jsxReturn && !nullReturn) return null
+        // Reject clauses that carry extra statements around the return (a
+        // local `const`, an expression statement, …): folding drops them, the
+        // same branch-local-preamble gap as `isDirectReturnBlock`. A bare
+        // `break` is fine. (#2377 review.)
+        if (!caseClauseIsDirectReturn(clause)) return null
 
         if (ts.isCaseClause(clause)) {
           branches.push({
             condition: clause.expression,
             jsxReturn: jsxReturn ?? null,
+            extraCaseConditions: pendingCases.length > 0 ? pendingCases : undefined,
           })
+          pendingCases = []
         } else {
+          // `default`. A fallthrough INTO default (`case 'a': default:`) would
+          // need the accumulated cases to also hit the default body — an
+          // unusual shape; bail rather than guess.
+          if (pendingCases.length > 0) return null
           fallback = jsxReturn ?? null
         }
       }
+      // Trailing empty case labels with no following body (`case 'z':` last,
+      // no return anywhere after) — nothing to attach them to; bail.
+      if (pendingCases.length > 0) return null
 
       if (branches.length === 0) return null
-      return { branches, fallback, switchDiscriminant: stmt.expression }
+      if (preambleUnsafe(preamble, branches, fallback)) return null
+      return { branches, fallback, switchDiscriminant: stmt.expression, preamble }
     }
 
     // Trailing return <jsx> or return null — this is the fallback
@@ -2183,16 +2271,36 @@ function extractMultiReturnJsxBranches(
       continue
     }
 
-    // Reject bodies with variable declarations — locals referenced in
-    // conditions or JSX would become undefined after inlining.
-    if (ts.isVariableStatement(stmt)) return null
+    // Leading `const`/`let` before any branch — collected as a preamble when
+    // the caller allows it (the `.map()` body fold; Stage 2 of
+    // spec/callback-fidelity.md). The JS-runtime fold emits it once per
+    // iteration ahead of the conditional; a DSL target refuses (BF021 +
+    // `/* @client */`) since it can't carry the loop-local into a branch
+    // template. Without `allowPreamble`, or once branches have started, reject:
+    // the helper-function inliner has no place to emit it, and a mid-chain
+    // local referenced in a later condition/JSX would become undefined.
+    if (ts.isVariableStatement(stmt)) {
+      // Only `const` / `let` are collectable — a `var` hoists to the enclosing
+      // function scope with different (redeclaration / TDZ-free) semantics that
+      // the per-iteration preamble emit wouldn't preserve, so reject it.
+      // (#2379 review.)
+      const declFlags = stmt.declarationList.flags
+      const isConstOrLet =
+        (declFlags & ts.NodeFlags.Const) !== 0 || (declFlags & ts.NodeFlags.Let) !== 0
+      if (allowPreamble && isConstOrLet && branches.length === 0 && fallback === null) {
+        preamble.push(stmt)
+        continue
+      }
+      return null
+    }
 
     // Any other statement type → unsupported pattern
     return null
   }
 
   if (branches.length === 0) return null
-  return { branches, fallback }
+  if (preambleUnsafe(preamble, branches, fallback)) return null
+  return { branches, fallback, preamble }
 }
 
 /**
@@ -2208,18 +2316,17 @@ function isDirectReturnBlock(node: ts.Statement): boolean {
     for (const stmt of node.statements) {
       if (ts.isReturnStatement(stmt)) {
         returnCount++
-      } else if (
-        ts.isIfStatement(stmt) ||
-        ts.isSwitchStatement(stmt) ||
-        ts.isForStatement(stmt) ||
-        ts.isForOfStatement(stmt) ||
-        ts.isForInStatement(stmt) ||
-        ts.isWhileStatement(stmt) ||
-        ts.isDoStatement(stmt) ||
-        ts.isTryStatement(stmt)
-      ) {
-        return false
+        continue
       }
+      // Any non-return statement — a local `const`/`let`, an expression
+      // statement, or nested control flow (if/switch/for/while/try) — means
+      // this is not a *direct* return block. Folding it into an
+      // `IRConditional` branch would silently DROP the statement: the neutral
+      // IR has no per-branch carrier for a local, so a branch-local
+      // `const x = …; return <A>{x}</A>` renders `x` undefined (ReferenceError
+      // at SSR/hydration). Bail so the caller falls back conservatively.
+      // (#2377 review; Stage 2 of spec/callback-fidelity.md.)
+      return false
     }
     return returnCount === 1
   }
@@ -2253,6 +2360,37 @@ function findJsxReturnInCaseClause(
   return null
 }
 
+/**
+ * True when a `switch` case/default clause contains exactly one `return` and
+ * nothing else that would be dropped by the fold (a trailing `break` is
+ * allowed). Rejects clauses with a local `const`/`let`, an expression
+ * statement, or nested control flow — those have no per-branch preamble
+ * carrier in the folded `IRConditional`. (#2377 review; Stage 2 of
+ * spec/callback-fidelity.md.)
+ */
+function caseClauseIsDirectReturn(clause: ts.CaseClause | ts.DefaultClause): boolean {
+  let returnCount = 0
+  let seenReturn = false
+  for (const stmt of clause.statements) {
+    if (ts.isReturnStatement(stmt)) {
+      returnCount++
+      seenReturn = true
+      continue
+    }
+    if (ts.isBreakStatement(stmt)) {
+      // A `break` BEFORE the return makes the return unreachable — at runtime
+      // the case exits and the callback falls through to `undefined`, so
+      // folding it as if it returned JSX would render the wrong branch. Only a
+      // trailing break (after the return; dead but harmless) is allowed.
+      // (#2378 review.)
+      if (!seenReturn) return false
+      continue
+    }
+    return false
+  }
+  return returnCount === 1
+}
+
 function findNullReturnInCaseClause(
   clause: ts.CaseClause | ts.DefaultClause
 ): boolean {

package/src/compiler.ts

@@ -119,7 +119,7 @@ function compileMultipleComponents(
   const program = options.program ?? (needsTypeBasedDetection(source) ? createProgramForFile(source, filePath)?.program : undefined)
 
   for (const componentName of componentNames) {
-    const ctx = analyzeComponent(source, filePath, componentName, program)
+    const ctx = analyzeComponent(source, filePath, componentName, program, adapter.acceptsCallbackBody)
 
     if (!ctx.jsxReturn) {
       errors.push(...ctx.errors)
@@ -556,7 +556,7 @@ export function compileJSX(
   }
 
   // Single component flow
-  const ctx = analyzeComponent(compileSource, filePath, undefined, options.program)
+  const ctx = analyzeComponent(compileSource, filePath, undefined, options.program, options.adapter.acceptsCallbackBody)
 
   if (!ctx.jsxReturn) {
     errors.push(...ctx.errors)

package/src/expression-parser.ts

@@ -364,25 +364,22 @@ export interface SupportResult {
 // evaluate JS at runtime via hono/jsx) so this set only constrains
 // the template-language adapters.
 const UNSUPPORTED_METHODS = new Set([
-  // Higher-order array methods. Seven of these (`filter`, `every`,
-  // `some`, `find`, `findIndex`, `findLast`, `findLastIndex`) are
-  // intercepted as `higher-order` IR before reaching this gate.
-  // `map` is intercepted as an IRLoop when its callback returns JSX,
-  // and as a `CALLBACK_METHODS` evaluator lowering (`map_eval`, #2073)
-  // when it returns a value — it stays listed here so the fall-throughs
-  // (a bare `arr.map` reference, a function-reference callback) still
-  // refuse loudly. `reduce` / `reduceRight` stay
-  // listed here so the shapes the Tier C catalogue can't lower still
-  // refuse loudly: the `convertNode` call branch intercepts a matching
-  // `.reduce(fn, init)` / `.reduceRight(fn, init)` into the structured
-  // `array-method` + `ReduceOp` form *before* this gate (returning
-  // early), so only the unlowerable fall-throughs (a `.reduce(fn)` with
-  // no initial value, or a bare method reference) reach the gate and
-  // refuse. A 2-arg call whose reducer/init shape is off-catalogue
-  // returns an explicit `unsupported` from the call branch with a richer
-  // message. The rest stay refused — see #1448 Tier C for the design
-  // questions. `forEach` carries a tailored reason (see
-  // `UNSUPPORTED_METHOD_REASONS`).
+  // Higher-order array methods. `filter`, `every`, `some`, `find`,
+  // `findIndex`, `findLast`, `findLastIndex`, `reduce`, `reduceRight`
+  // and `flatMap` *with an arrow-callback argument* are recognized by
+  // `asCallbackMethodCall` and lower via the runtime evaluator
+  // (`serializeParsedExpr`) in the `call` arm ABOVE this gate — an
+  // off-subset callback body refuses there with a "complex callback"
+  // reason, not here. They stay listed in this set so the shapes that
+  // recognition can't catch — a BARE method reference (`arr.filter`
+  // uncalled) or a function-reference callback (no arrow) — still refuse
+  // loudly. (`reduce` / `reduceRight` are NOT folded into a structured
+  // `array-method` / `ReduceOp` form: #2018 P5 leaves them as a generic
+  // `call` whose reducer body + initial value serialize to the
+  // evaluator.) `map` is intercepted as an IRLoop when its callback
+  // returns JSX, and as a `CALLBACK_METHODS` evaluator lowering
+  // (`map_eval`, #2073) when it returns a value. `forEach` carries a
+  // tailored reason (see `UNSUPPORTED_METHOD_REASONS`).
   // `flat` is no longer here — `.flat(depth?)` lowers via the
   // `array-method` IR (structured `FlatDepth`) + `bf_flat` (Go) /
   // `bf->flat` (Mojo). `flatMap` stays listed as a fallback: the
@@ -395,6 +392,17 @@ const UNSUPPORTED_METHODS = new Set([
   // `IRLoop` upstream. See #1448.
   'filter', 'map', 'reduce', 'reduceRight', 'every', 'some',
   'forEach', 'flatMap',
+  // `fill` has no template lowering on any DSL adapter (it mutates the
+  // receiver in place and returns it — no ParsedExpr / evaluator form).
+  // Before it was listed here `isSupported` reported it "supported" and
+  // the adapters emitted a raw `.fill(...)` method call with no build
+  // diagnostic — the same silent footgun the string methods below
+  // documented before they were gated: it only surfaced as a crash at
+  // template-render time. Listing it makes the build fail loudly with
+  // BF101, pointing users at the `/* @client */` escape (a JS-runtime
+  // adapter still runs it verbatim, since those skip `isSupported`).
+  // See spec/callback-fidelity.md.
+  'fill',
   // #1448 Tier A — Array methods. Each method PR adds the lowering
   // (typically a new `array-method` variant or runtime helper) and
   // removes its row here. See packages/adapter-tests/fixtures/methods/.

package/src/ir-to-client-js/build-references.ts

@@ -35,6 +35,7 @@ import type {
   ReferenceSource,
   ReferencesGraph,
 } from '../types.ts'
+import { preambleAnalysisText } from '../types.ts'
 import type { IRVisitor as WalkerVisitor } from './walker.ts'
 import { attrValueToString } from './utils.ts'
 import type { ClientJsContext } from './types.ts'
@@ -151,7 +152,14 @@ export function buildReferencesGraph(ctx: ClientJsContext, irRoot: IRNode): Refe
     }
     if (elem.filterPredicate) addExprEdges(ROOT_SOURCE, elem.filterPredicate.raw, 'template-closure')
     if (elem.sortComparator) addExprEdges(ROOT_SOURCE, elem.sortComparator.raw, 'template-closure')
-    if (elem.mapPreamble) addExprEdges(ROOT_SOURCE, elem.mapPreamble, 'template-closure')
+    if (elem.preamble) addExprEdges(ROOT_SOURCE, preambleAnalysisText(elem.preamble), 'template-closure')
+    // flatMap descriptor bodies (`elem.flatMapClient`) are NOT traced here:
+    // the rendered body embeds leaf HTML template literals, and the regex
+    // identifier extractor would turn tag/attr names into false-positive
+    // edges. The Phase 3 loop visitor traces the same content structurally
+    // (js segments via `preambleAnalysisText`, leaf attrs/keys/interpolations
+    // via `walkIR` on `flatMapCallback` segments) — that's what keeps
+    // `const maxTags = _p.maxTags` in the extracted props.
     for (const attr of elem.bindings.reactiveAttrs) {
       addExprEdges(ROOT_SOURCE, attr.expression, 'template-closure')
     }
@@ -316,7 +324,16 @@ export function buildReferencesGraph(ctx: ClientJsContext, irRoot: IRNode): Refe
       addExprEdges(ROOT_SOURCE, l.array, 'template-closure')
       if (l.filterPredicate) addExprEdges(ROOT_SOURCE, l.filterPredicate.raw, 'template-closure')
       if (l.sortComparator) addExprEdges(ROOT_SOURCE, l.sortComparator.raw, 'template-closure')
-      if (l.mapPreamble) addExprEdges(ROOT_SOURCE, l.mapPreamble, 'template-closure')
+      if (l.preamble) addExprEdges(ROOT_SOURCE, preambleAnalysisText(l.preamble), 'template-closure')
+      // flatMap bodies: js segments reference init-scope names; segment
+      // leaves are IR nodes off `children`, so `descend()` never reaches
+      // them — walk them explicitly (mirrors attachParsedExpressions).
+      if (l.flatMapCallback) {
+        addExprEdges(ROOT_SOURCE, preambleAnalysisText(l.flatMapCallback), 'template-closure')
+        for (const seg of l.flatMapCallback.segments) {
+          if (seg.kind === 'jsx') walkIR(seg.ir, null, visitor)
+        }
+      }
       descend()
       if (l.childComponent) walkChildComponent(l.childComponent)
       if (l.nestedComponents) {

package/src/ir-to-client-js/collect-elements.ts

@@ -6,7 +6,7 @@ import { type IRNode, type IRElement, type IRComponent, type IRLoop, type IRProp
 import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, LoopOffset, NestedLoop } from './types.ts'
 import { attrValueToString, freeIdsFromRefs, quotePropName, PROPS_PARAM } from './utils.ts'
 import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings } from './reactivity.ts'
-import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, type SkeletonSlotPaths } from './html-template.ts'
+import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, renderFlatMapClientBody, renderFlatMapProjectionClientBody, flatMapCallbackHasKeyedLeaf, type SkeletonSlotPaths } from './html-template.ts'
 import { templateRootIsSvg } from './control-flow/stringify/template-parse.ts'
 import { expandDynamicPropValue, expandConstantForReactivity } from './prop-handling.ts'
 import { walkIR, stopAt } from './walker.ts'
@@ -393,7 +393,7 @@ export function collectInnerLoops(
           objectIteration: n.objectIteration,
           containerSlotId: scope.parentSlotId,
           template,
-          mapPreamble: n.mapPreamble,
+          preamble: n.preamble,
           refsOuterParam: refsOuter,
           childComponents,
           insideConditional: !flat && scope.insideCond ? true : undefined,
@@ -650,10 +650,26 @@ export function collectElements(
       // are extracted explicitly below for the closure capture set.
       if (!l.slotId || inCond) return
 
+      // flatMap PROJECTION loop: the only child is a nested IRLoop lowered
+      // from `flatMap(it => it.tags.map(...))`. The children exist for SSR
+      // templatization (nested {{range}} on DSL adapters); the CLIENT
+      // reconciles the flattened leaves through the descriptor mapArray
+      // path synthesized from the same inner loop, so none of the
+      // children-derived client machinery (bindings, inner-loop plans,
+      // per-row template) applies — leaf wiring was refused at IR build.
+      const projectionInner =
+        l.method === 'flatMap' && l.children.length === 1 && l.children[0].type === 'loop'
+          ? l.children[0]
+          : undefined
+
       const childHandlers: string[] = []
-      const bindings = collectLoopChildBindings(l.children, ctx, siblingOffsets, l.param, l.paramBindings)
-      for (const child of l.children) {
-        childHandlers.push(...collectEventHandlersFromIR(child))
+      const bindings = projectionInner
+        ? emptyLoopChildBindings()
+        : collectLoopChildBindings(l.children, ctx, siblingOffsets, l.param, l.paramBindings)
+      if (!projectionInner) {
+        for (const child of l.children) {
+          childHandlers.push(...collectEventHandlersFromIR(child))
+        }
       }
 
       if (l.childComponent) {
@@ -668,7 +684,9 @@ export function collectElements(
       // Determine rendering strategy for dynamic arrays:
       // Use element reconciliation when the loop body has nested components,
       // or when inner loops need their own mapArray for events/reactive text.
-      const { useElementReconciliation, innerLoops } = decideLoopRendering(l, siblingOffsets, ctx)
+      const { useElementReconciliation, innerLoops } = projectionInner
+        ? { useElementReconciliation: false, innerLoops: undefined }
+        : decideLoopRendering(l, siblingOffsets, ctx)
 
       let template = ''
       let staticItemTemplate: string | undefined
@@ -691,7 +709,7 @@ export function collectElements(
           // `data-key`, mirroring the SSR template's renderChild emit.
           staticItemTemplate = irToHtmlTemplate(l.children[0], buildRestSpreadNames(ctx), 0, undefined, undefined, /* insideLoop */ true)
         }
-      } else if (l.children[0]) {
+      } else if (l.children[0] && !projectionInner) {
         // Pass loopParams so expressions are wrapped at generation time,
         // avoiding post-hoc regex wrapping that corrupts literal attribute values.
         // Forward destructured bindings (#951) so references like `cfg.color`
@@ -776,7 +794,21 @@ export function collectElements(
           raw: l.sortComparator.raw,
         } : undefined,
         chainOrder: l.chainOrder,
-        mapPreamble: l.mapPreamble,
+        preamble: l.preamble,
+        preambleRegions: l.preambleRegions,
+        flatMapClient: projectionInner
+          ? {
+              params: l.index ? `(${l.param}, ${l.index})` : `(${l.param})`,
+              body: renderFlatMapProjectionClientBody(projectionInner, buildRestSpreadNames(ctx)),
+              keyed: projectionInner.key !== null,
+            }
+          : l.flatMapCallback
+            ? {
+                params: l.flatMapCallback.params,
+                body: renderFlatMapClientBody(l.flatMapCallback, buildRestSpreadNames(ctx)),
+                keyed: flatMapCallbackHasKeyedLeaf(l.flatMapCallback),
+              }
+            : undefined,
       })
       // Don't descend — loop-scoped variables are only available inside the iteration.
     },
@@ -1069,8 +1101,16 @@ function collectBranchLoops(
       // reactive-text collection on inner loops reached from this call path
       // is handled at the enclosing branch-loop level below (`if (ctx)` block
       // around `collectLoopChildReactiveTexts`), not per inner loop.
-      const { useElementReconciliation, innerLoops: innerLoopsCollected } =
-        decideLoopRendering(n, siblingOffsets, undefined)
+      // flatMap PROJECTION loop — see the top-level handler's note: children
+      // are SSR-only; the client rides the descriptor mapArray path.
+      const projectionInner =
+        n.method === 'flatMap' && n.children.length === 1 && n.children[0].type === 'loop'
+          ? n.children[0]
+          : undefined
+
+      const { useElementReconciliation, innerLoops: innerLoopsCollected } = projectionInner
+        ? { useElementReconciliation: false, innerLoops: undefined }
+        : decideLoopRendering(n, siblingOffsets, undefined)
 
       // Build the item template from loop children.
       // Use loopDepth=0: this loop gets its own reconcileElements (independent
@@ -1080,7 +1120,9 @@ function collectBranchLoops(
       // use `param()` to read the current item value.
       let childTemplate: string
       const branchLoopParamSpec = [{ param: n.param, bindings: n.paramBindings }]
-      if (useElementReconciliation && n.children[0]) {
+      if (projectionInner) {
+        childTemplate = '' // descriptor renderItem builds from d.h, not a row template
+      } else if (useElementReconciliation && n.children[0]) {
         childTemplate = irToPlaceholderTemplate(n.children[0], restNames, 0, branchLoopParamSpec)
       } else {
         childTemplate = n.children.map(c => irToHtmlTemplate(c, undefined, 0, branchLoopParamSpec)).join('')
@@ -1092,7 +1134,7 @@ function collectBranchLoops(
       // memos). Previously these were only collected for composite loops,
       // which caused reactive reads inside simple loop bodies to silently
       // no-op for existing items.
-      const branchBindings = ctx
+      const branchBindings = ctx && !projectionInner
         ? collectLoopChildBindings(n.children, ctx, siblingOffsets, n.param, n.paramBindings)
         : emptyLoopChildBindings()
 
@@ -1111,7 +1153,8 @@ function collectBranchLoops(
         objectIteration: n.objectIteration,
         template: childTemplate,
         containerSlotId: containerSlot,
-        mapPreamble: n.mapPreamble ?? null,
+        preamble: n.preamble,
+        preambleRegions: n.preambleRegions,
         nestedComponents: useElementReconciliation ? n.nestedComponents : undefined,
         bindings: branchBindings,
         innerLoops: useElementReconciliation ? innerLoopsCollected : undefined,
@@ -1126,6 +1169,19 @@ function collectBranchLoops(
           raw: n.sortComparator.raw,
         } : undefined,
         chainOrder: n.chainOrder,
+        flatMapClient: projectionInner
+          ? {
+              params: n.index ? `(${n.param}, ${n.index})` : `(${n.param})`,
+              body: renderFlatMapProjectionClientBody(projectionInner, restNames),
+              keyed: projectionInner.key !== null,
+            }
+          : n.flatMapCallback
+            ? {
+                params: n.flatMapCallback.params,
+                body: renderFlatMapClientBody(n.flatMapCallback, restNames),
+                keyed: flatMapCallbackHasKeyedLeaf(n.flatMapCallback),
+              }
+            : undefined,
       })
       // Don't recurse into the loop — nested loops are handled by the loop's own reconciliation.
     },

package/src/ir-to-client-js/control-flow/plan/branch-loop.ts

@@ -15,12 +15,20 @@
  * pair.
  */
 
-import type { CompositeLoopPlan, LoopChildRefBinding } from './loop.ts'
+import type { CompositeLoopPlan, LoopChildRefBinding, PreambleRegionPlan } from './loop.ts'
 import type { EventDelegationPlan } from './event-delegation.ts'
 import type { ReactiveEffectsPlan } from './reactive-effects.ts'
 
 export interface BranchPlainLoopPlan {
+  /**
+   * flatMap descriptor mode — see `PlainLoopVariant.flatMapLeafItem`
+   * (plan/loop.ts): `arrayExpr` already flattens through the descriptor
+   * body and the stringifier emits the build-or-patch renderItem.
+   */
+  flatMapLeafItem?: boolean
   kind: 'plain'
+  /** See LoopPlanCommon.rowConstruction — required on every variant. */
+  rowConstruction: 'string-template' | 'dom-ops'
   /**
    * Variable suffix for the container lookup — e.g. for slotId `s4` the
    * stringifier emits `__loop_s4` and queries via `$(__branchScope, 's4')`.
@@ -76,6 +84,11 @@ export interface BranchPlainLoopPlan {
    * Undefined off → byte-identical (SR8).
    */
   profileLoopId?: string
+  /**
+   * Preamble-patched regions (#2389) — non-empty forces the multi-line
+   * renderItem layout, mirroring the top-level plain plan.
+   */
+  preambleRegions: readonly PreambleRegionPlan[]
 }
 
 export interface BranchCompositeLoopPlan {

package/src/ir-to-client-js/control-flow/plan/build-branch-loop.ts

@@ -15,7 +15,8 @@ import { buildChainedArrayExpr, varSlotId, wrapLoopParamAsAccessor } from '../..
 import { buildBranchCompositePlan } from './build-composite-loop.ts'
 import { buildBranchLoopDelegationPlan } from './build-event-delegation.ts'
 import { buildReactiveEffectsPlan } from './build-reactive-effects.ts'
-import { destructureLoopParam, loopKeyFn, buildChildRefBindings } from '../shared.ts'
+import { destructureLoopParam, loopKeyFn, buildChildRefBindings, buildPreambleRegionPlans } from '../shared.ts'
+import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
   BranchCompositeLoopPlan,
   BranchLoopPlan,
@@ -42,20 +43,31 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
     || loop.bindings.reactiveTexts.length > 0
     || loop.bindings.conditionals.length > 0
 
+  // flatMap descriptor mode — see buildPlainLoopPlan (build-loop.ts).
+  const fm = loop.flatMapClient
   const plan: BranchPlainLoopPlan = {
     kind: 'plain',
+    rowConstruction: 'string-template',
     containerSlotId,
     containerVar,
     markerId: loop.markerId,
-    arrayExpr: buildChainedArrayExpr(loop),
-    keyFn: loopKeyFn(loop),
+    flatMapLeafItem: fm ? true : undefined,
+    arrayExpr: fm
+      ? `(${buildChainedArrayExpr(loop)}).flatMap(${fm.params} => ${fm.body})`
+      : buildChainedArrayExpr(loop),
+    keyFn: fm
+      ? (fm.keyed ? '(__bfD, __bfI) => String(__bfD.k ?? __bfI)' : 'null')
+      : loopKeyFn(loop),
     paramHead,
     paramUnwrap,
     indexParam: loop.index || '__idx',
     // Wrap loop-param references to signal-accessor form so the preamble
     // matches the template literal's already-wrapped reads (#1065).
-    mapPreambleWrapped: loop.mapPreamble
-      ? wrapLoopParamAsAccessor(loop.mapPreamble, loop.param, loop.paramBindings)
+    mapPreambleWrapped: loop.preamble
+      ? renderPreamble(loop.preamble, {
+          transformJs: (t) => wrapLoopParamAsAccessor(t, loop.param, loop.paramBindings),
+          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
+        })
       : '',
     template: loop.template,
     reactiveEffects: hasReactiveEffects
@@ -70,6 +82,7 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
       : null,
     eventDelegation: buildBranchLoopDelegationPlan(loop, cv, profileComponentName),
     childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings),
+    preambleRegions: buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings),
     bodyIsMultiRoot: loop.bodyIsMultiRoot ?? false,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${containerSlotId}` : undefined,
   }