@barefootjs/jsx 0.26.2 → 0.26.4

package/dist/index.js

@@ -250,6 +250,7 @@ var UNSUPPORTED_METHODS = new Set([
   "some",
   "forEach",
   "flatMap",
+  "fill",
   "charAt",
   "charCodeAt",
   "codePointAt",
@@ -3251,7 +3252,7 @@ function templateAttrExpr(attrName, valExpr, presenceOrUndefined) {
     return `\${((v) => v != null ? 'style="' + ${escapeAttrValueExpr("v")} + '"' : '')(styleToCss(${valExpr}))}`;
   }
   if (attrName === "data-key" || attrName.startsWith("data-key-")) {
-    return `${attrName}="\${${valExpr}}"`;
+    return `${attrName}="\${${escapeAttrValueExpr(valExpr)}}"`;
   }
   return `\${(${valExpr}) != null ? '${attrName}="' + ${escapeAttrValueExpr(valExpr)} + '"' : ''}`;
 }
@@ -3380,6 +3381,86 @@ function buildSpreadAttrsMergeCall(args) {
 function itemAnchorTemplate(keyExpr) {
   return `<!--${loopItemMarker("${" + keyExpr + "}")}-->`;
 }
+function renderPreamble(preamble, opts) {
+  let out = "";
+  for (const seg of preamble.segments) {
+    if (seg.kind === "js") {
+      const text = opts.textVariant === "template" ? seg.templateText ?? seg.text : seg.text;
+      out += opts.transformJs ? opts.transformJs(text) : text;
+    } else if (opts.rawLeaf) {
+      out += opts.renderLeaf(escapeLeafTextExpressions(seg.ir));
+    } else {
+      out += "`" + opts.renderLeaf(escapeLeafTextExpressions(seg.ir)) + "`";
+    }
+  }
+  return out;
+}
+function flatMapLeafKeyExpr(ir) {
+  if (ir.type !== "element")
+    return null;
+  const keyAttr = ir.attrs.find((a) => a.name === "key");
+  if (!keyAttr)
+    return null;
+  switch (keyAttr.value.kind) {
+    case "expression":
+      return `(${keyAttr.value.expr})`;
+    case "literal":
+      return JSON.stringify(keyAttr.value.value);
+    case "template":
+      return attrValueToString(keyAttr.value);
+    default:
+      return null;
+  }
+}
+function stripLeafKeyAttr(ir) {
+  if (ir.type !== "element")
+    return ir;
+  return { ...ir, attrs: ir.attrs.filter((a) => a.name !== "key") };
+}
+function renderFlatMapClientBody(cb, restSpreadNames) {
+  return renderPreamble(cb, {
+    textVariant: "client",
+    rawLeaf: true,
+    renderLeaf: (ir) => {
+      const key = flatMapLeafKeyExpr(ir);
+      const html = irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, 1, undefined, undefined, true);
+      return `({ k: ${key ?? "undefined"}, h: \`${html}\` })`;
+    }
+  });
+}
+function flatMapCallbackHasKeyedLeaf(cb) {
+  return cb.segments.some((s) => s.kind === "jsx" && flatMapLeafKeyExpr(s.ir) !== null);
+}
+function renderFlatMapProjectionClientBody(inner, restSpreadNames) {
+  const chained = applyLoopChain(inner);
+  const params = inner.index ? `(${inner.param}, ${inner.index})` : `(${inner.param})`;
+  const key = inner.key ? `(${inner.key})` : "undefined";
+  const html = inner.children.map((c) => irToHtmlTemplate(escapeLeafTextExpressions(c), restSpreadNames, 1, undefined, undefined, true)).join("");
+  return `${chained}.map(${params} => ({ k: ${key}, h: \`${html}\` }))`;
+}
+function escapeLeafTextExpressions(ir) {
+  switch (ir.type) {
+    case "element":
+      return { ...ir, children: ir.children.map(escapeLeafTextExpressions) };
+    case "fragment":
+      return { ...ir, children: ir.children.map(escapeLeafTextExpressions) };
+    case "expression": {
+      if (ir.expr === "null" || ir.expr === "undefined")
+        return ir;
+      if (ir.slotId || ir.expr.trimStart().startsWith("escapeText("))
+        return ir;
+      return { ...ir, expr: `escapeText((${ir.expr}))`, templateExpr: ir.templateExpr ? `escapeText((${ir.templateExpr}))` : ir.templateExpr };
+    }
+    case "conditional":
+      return {
+        ...ir,
+        whenTrue: escapeLeafTextExpressions(ir.whenTrue),
+        whenFalse: ir.whenFalse ? escapeLeafTextExpressions(ir.whenFalse) : ir.whenFalse
+      };
+    default:
+      return ir;
+  }
+}
 function irToHtmlTemplate(node, restSpreadNames, loopDepth = 0, loopParams, branchSlotsVar, insideLoop = false, inHoistedChildren = false) {
   const recurse = (n) => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, insideLoop, inHoistedChildren);
   const wrapExpr = (expr) => wrapExprWithLoopParams(expr, loopParams);
@@ -3421,15 +3502,17 @@ function irToHtmlTemplate(node, restSpreadNames, loopDepth = 0, loopParams, bran
     }
     case "text":
       return escapeHtml(node.value);
-    case "expression":
+    case "expression": {
       if (node.expr === "null" || node.expr === "undefined")
         return "";
+      const inner = wrapInterpolation(wrapExpr(node.expr));
+      const valueExpr = node.joinArrayChild ? `Array.isArray(${inner}) ? ${inner}.join('') : (${inner} ?? '')` : inner;
       if (node.slotId) {
-        const inner = wrapInterpolation(wrapExpr(node.expr));
-        const slotted = branchSlotsVar ? inner : escapeTextSlotExpr(inner);
+        const slotted = branchSlotsVar || node.joinArrayChild ? valueExpr : escapeTextSlotExpr(valueExpr);
         return `<!--bf:${node.slotId}-->\${${slotted}}<!--/-->`;
       }
-      return `\${${wrapInterpolation(wrapExpr(node.expr))}}`;
+      return `\${${valueExpr}}`;
+    }
     case "conditional": {
       const trueBranch = recurse(node.whenTrue);
       const falseBranch = recurse(node.whenFalse);
@@ -3488,14 +3571,13 @@ function irToHtmlTemplate(node, restSpreadNames, loopDepth = 0, loopParams, bran
       const iterMethod = node.method ?? "map";
       let mapExpr;
       if (node.flatMapCallback) {
-        let body = node.flatMapCallback.templateBody ?? node.flatMapCallback.body;
-        for (const frag of node.flatMapCallback.fragments) {
-          const renderedIr = irToHtmlTemplate(frag.ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop);
-          body = body.replace(frag.placeholder, `\`${renderedIr}\``);
-        }
+        const body = renderPreamble(node.flatMapCallback, {
+          renderLeaf: (ir) => irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop)
+        });
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`;
-      } else if (node.mapPreamble) {
-        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`;
+      } else if (node.preamble) {
+        const preamble = renderPreamble(node.preamble, { textVariant: "client", renderLeaf: (ir) => irToHtmlTemplate(ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop) });
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`;
       } else {
         mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`;
       }
@@ -3743,13 +3825,16 @@ function irToPlaceholderTemplate(node, restSpreadNames, loopDepth = 0, loopParam
     }
     case "text":
       return escapeHtml(node.value);
-    case "expression":
+    case "expression": {
       if (node.expr === "null" || node.expr === "undefined")
         return "";
+      const wrapped = wrapExpr(node.expr);
+      const value = node.joinArrayChild ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')` : wrapped;
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(wrapExpr(node.expr))}}<!--/-->`;
+        return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped)}}<!--/-->`;
       }
-      return `\${${wrapExpr(node.expr)}}`;
+      return `\${${value}}`;
+    }
     case "conditional": {
       const trueBranch = recurse(node.whenTrue);
       const falseBranch = recurse(node.whenFalse);
@@ -3776,14 +3861,13 @@ function irToPlaceholderTemplate(node, restSpreadNames, loopDepth = 0, loopParam
       const iterMethod = node.method ?? "map";
       let mapExpr;
       if (node.flatMapCallback) {
-        let body = node.flatMapCallback.templateBody ?? node.flatMapCallback.body;
-        for (const frag of node.flatMapCallback.fragments) {
-          const renderedIr = irToPlaceholderTemplate(frag.ir, restSpreadNames, loopDepth + 1, loopParams);
-          body = body.replace(frag.placeholder, `\`${renderedIr}\``);
-        }
+        const body = renderPreamble(node.flatMapCallback, {
+          renderLeaf: (ir) => irToPlaceholderTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams)
+        });
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`;
-      } else if (node.mapPreamble) {
-        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`;
+      } else if (node.preamble) {
+        const preamble = renderPreamble(node.preamble, { textVariant: "client", renderLeaf: (ir) => irToPlaceholderTemplate(ir, restSpreadNames, loopDepth + 1, loopParams) });
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`;
       } else {
         mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`;
       }
@@ -3971,13 +4055,16 @@ function irToComponentTemplateWithOpts(node, opts) {
     }
     case "text":
       return escapeHtml(node.value);
-    case "expression":
+    case "expression": {
       if (node.expr === "null" || node.expr === "undefined")
         return "";
+      const wrapped = transformExpr(node.expr, node.templateExpr);
+      const value = node.joinArrayChild ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')` : wrapped;
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(transformExpr(node.expr, node.templateExpr))}}<!--/-->`;
+        return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped)}}<!--/-->`;
       }
-      return `\${${transformExpr(node.expr, node.templateExpr)}}`;
+      return `\${${value}}`;
+    }
     case "conditional": {
       if (node.clientOnly && node.slotId) {
         return `<!--bf-cond-start:${node.slotId}--><!--bf-cond-end:${node.slotId}-->`;
@@ -4298,10 +4385,11 @@ function generateCsrTemplateWithOpts(node, opts) {
       {
         const transformed = transformExpr(node.expr, node.templateExpr);
         const expr = transformed === UNSAFE_TEMPLATE_EXPR ? "''" : transformed;
+        const value = node.joinArrayChild ? `Array.isArray(${expr}) ? ${expr}.join('') : (${expr} ?? '')` : expr;
         if (node.slotId) {
-          return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(expr)}}<!--/-->`;
+          return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(expr)}}<!--/-->`;
         }
-        return `\${${expr}}`;
+        return `\${${value}}`;
       }
     case "conditional": {
       if (node.clientOnly && node.slotId) {
@@ -4397,16 +4485,14 @@ function generateCsrTemplateWithOpts(node, opts) {
       const iterMethod = node.method ?? "map";
       let mapExpr;
       if (node.flatMapCallback) {
-        let body = node.flatMapCallback.templateBody ?? node.flatMapCallback.body;
-        for (const frag of node.flatMapCallback.fragments) {
-          const renderedIr = recurseInLoopBody(frag.ir);
-          body = body.replace(frag.placeholder, `\`${renderedIr}\``);
-        }
-        body = applyPropsRewrite(body, propsObjectName ?? null);
+        const body = renderPreamble(node.flatMapCallback, {
+          textVariant: "template",
+          transformJs: (t) => applyPropsRewrite(t, propsObjectName ?? null),
+          renderLeaf: (ir) => recurseInLoopBody(stripLeafKeyAttr(ir))
+        });
         mapExpr = `\${${iterArrayExpr}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`;
-      } else if (node.mapPreamble) {
-        const rawPreamble = node.templateMapPreamble ?? node.mapPreamble;
-        const preamble = applyPropsRewrite(rawPreamble, propsObjectName ?? null);
+      } else if (node.preamble) {
+        const preamble = renderPreamble(node.preamble, { textVariant: "template", transformJs: (t) => applyPropsRewrite(t, propsObjectName ?? null), renderLeaf: (ir) => recurseInLoopBody(ir) });
         mapExpr = `\${${iterArrayExpr}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`;
       } else {
         mapExpr = `\${${iterArrayExpr}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`;
@@ -4561,6 +4647,39 @@ function reconstructWithoutTypes(node, sourceFile, ranges) {
   }
   return result;
 }
+function reconstructAsSegments(node, sourceFile, ranges, markers) {
+  const nodeStart = node.getStart(sourceFile);
+  const nodeEnd = node.getEnd();
+  const fullText = sourceFile.text;
+  const edits = [];
+  for (const r of ranges) {
+    if (r.end <= nodeStart || r.start >= nodeEnd)
+      continue;
+    edits.push({ start: r.start, end: r.end, marker: null });
+  }
+  markers.forEach((m, i) => edits.push({ start: m.start, end: m.end, marker: i }));
+  edits.sort((a, b) => a.start - b.start || b.end - a.end);
+  const segments = [];
+  let jsBuf = "";
+  let pos = nodeStart;
+  for (const edit of edits) {
+    if (edit.start < pos)
+      continue;
+    jsBuf += fullText.slice(pos, edit.start);
+    if (edit.marker !== null) {
+      if (jsBuf)
+        segments.push({ js: jsBuf });
+      jsBuf = "";
+      segments.push({ marker: edit.marker });
+    }
+    pos = edit.end;
+  }
+  if (pos < nodeEnd)
+    jsBuf += fullText.slice(pos, nodeEnd);
+  if (jsBuf)
+    segments.push({ js: jsBuf });
+  return segments;
+}
 function mergeRanges(ranges) {
   if (ranges.length === 0)
     return [];
@@ -4706,10 +4825,11 @@ function findAngleBracketAfter(lastTypeArg, fullText) {
 }
 
 // src/analyzer-context.ts
-function createAnalyzerContext(sourceFile, filePath) {
+function createAnalyzerContext(sourceFile, filePath, acceptsCallbackBody) {
   return {
     sourceFile,
     filePath,
+    acceptsCallbackBody,
     componentName: null,
     componentNode: null,
     hasDefaultExport: false,
@@ -4755,6 +4875,9 @@ function createAnalyzerContext(sourceFile, filePath) {
       } catch {
         ownSourceFile = undefined;
       }
+      if (process.env.BF_ASSERT_NO_JSX_IN_GETJS === "1" && this.errors.length === 0 && nodeContainsJsx(node)) {
+        throw new Error("getJS() called on a JSX-bearing node — raw JSX must never be spliced " + "into emitted output. Carry mixed content as structured segments " + "(MapCallbackPreamble / FlatMapCallback) instead.");
+      }
       if (ownSourceFile && ownSourceFile !== sourceFile) {
         return node.getText(ownSourceFile);
       }
@@ -4762,6 +4885,11 @@ function createAnalyzerContext(sourceFile, filePath) {
     }
   };
 }
+function nodeContainsJsx(node) {
+  if (ts7.isJsxElement(node) || ts7.isJsxSelfClosingElement(node) || ts7.isJsxFragment(node))
+    return true;
+  return ts7.forEachChild(node, nodeContainsJsx) ?? false;
+}
 function getSourceLocation(node, sourceFile, filePath) {
   const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());
   const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
@@ -5564,7 +5692,7 @@ function createProgramForFile(source, filePath) {
     return null;
   }
 }
-function analyzeComponent(source, filePath, targetComponentName, program) {
+function analyzeComponent(source, filePath, targetComponentName, program, acceptsCallbackBody) {
   incrementCounter("filesAnalyzed");
   const hadSharedProgram = program !== undefined;
   const prescan = prescanReactiveFactoriesInSource(source, filePath);
@@ -5597,7 +5725,7 @@ function analyzeComponent(source, filePath, targetComponentName, program) {
       checker = result.checker;
     }
   }
-  const ctx = createAnalyzerContext(sourceFile, filePath);
+  const ctx = createAnalyzerContext(sourceFile, filePath, acceptsCallbackBody);
   ctx.checker = checker;
   ctx.reactiveFactories = prescan.factories;
   ctx.declinedReactiveFactories = prescan.declined;
@@ -6649,9 +6777,15 @@ function extractSingleJsxReturn(body) {
     return null;
   return jsxReturn;
 }
-function extractMultiReturnJsxBranches(body) {
+function preambleUnsafe(preamble, branches, fallback) {
+  if (preamble.length === 0)
+    return false;
+  return fallback === null || branches.some((b) => b.jsxReturn === null);
+}
+function extractMultiReturnJsxBranches(body, allowPreamble = false) {
   const branches = [];
   let fallback = null;
+  const preamble = [];
   const stmts = body.statements;
   for (let i = 0;i < stmts.length; i++) {
     const stmt = stmts[i];
@@ -6681,7 +6815,9 @@ function extractMultiReturnJsxBranches(body) {
           }
           if (branches.length === 0)
             return null;
-          return { branches, fallback };
+          if (preambleUnsafe(preamble, branches, fallback))
+            return null;
+          return { branches, fallback, preamble };
         }
         break;
       }
@@ -6696,23 +6832,38 @@ function extractMultiReturnJsxBranches(body) {
       const hasDefault = stmt.caseBlock.clauses.some((c) => ts8.isDefaultClause(c));
       if (!hasDefault)
         return null;
+      let pendingCases = [];
       for (const clause of stmt.caseBlock.clauses) {
+        if (ts8.isCaseClause(clause) && clause.statements.length === 0) {
+          pendingCases.push(clause.expression);
+          continue;
+        }
         const jsxReturn = findJsxReturnInCaseClause(clause);
         const nullReturn = findNullReturnInCaseClause(clause);
         if (!jsxReturn && !nullReturn)
           return null;
+        if (!caseClauseIsDirectReturn(clause))
+          return null;
         if (ts8.isCaseClause(clause)) {
           branches.push({
             condition: clause.expression,
-            jsxReturn: jsxReturn ?? null
+            jsxReturn: jsxReturn ?? null,
+            extraCaseConditions: pendingCases.length > 0 ? pendingCases : undefined
           });
+          pendingCases = [];
         } else {
+          if (pendingCases.length > 0)
+            return null;
           fallback = jsxReturn ?? null;
         }
       }
+      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 };
     }
     if (ts8.isReturnStatement(stmt) && stmt.expression) {
       const expr = unwrapJsxTransparent(stmt.expression);
@@ -6723,13 +6874,22 @@ function extractMultiReturnJsxBranches(body) {
       }
       continue;
     }
-    if (ts8.isVariableStatement(stmt))
+    if (ts8.isVariableStatement(stmt)) {
+      const declFlags = stmt.declarationList.flags;
+      const isConstOrLet = (declFlags & ts8.NodeFlags.Const) !== 0 || (declFlags & ts8.NodeFlags.Let) !== 0;
+      if (allowPreamble && isConstOrLet && branches.length === 0 && fallback === null) {
+        preamble.push(stmt);
+        continue;
+      }
       return null;
+    }
     return null;
   }
   if (branches.length === 0)
     return null;
-  return { branches, fallback };
+  if (preambleUnsafe(preamble, branches, fallback))
+    return null;
+  return { branches, fallback, preamble };
 }
 function isDirectReturnBlock(node) {
   if (ts8.isReturnStatement(node))
@@ -6739,9 +6899,9 @@ function isDirectReturnBlock(node) {
     for (const stmt of node.statements) {
       if (ts8.isReturnStatement(stmt)) {
         returnCount++;
-      } else if (ts8.isIfStatement(stmt) || ts8.isSwitchStatement(stmt) || ts8.isForStatement(stmt) || ts8.isForOfStatement(stmt) || ts8.isForInStatement(stmt) || ts8.isWhileStatement(stmt) || ts8.isDoStatement(stmt) || ts8.isTryStatement(stmt)) {
-        return false;
+        continue;
       }
+      return false;
     }
     return returnCount === 1;
   }
@@ -6772,6 +6932,24 @@ function findJsxReturnInCaseClause(clause) {
   }
   return null;
 }
+function caseClauseIsDirectReturn(clause) {
+  let returnCount = 0;
+  let seenReturn = false;
+  for (const stmt of clause.statements) {
+    if (ts8.isReturnStatement(stmt)) {
+      returnCount++;
+      seenReturn = true;
+      continue;
+    }
+    if (ts8.isBreakStatement(stmt)) {
+      if (!seenReturn)
+        return false;
+      continue;
+    }
+    return false;
+  }
+  return returnCount === 1;
+}
 function findNullReturnInCaseClause(clause) {
   for (const stmt of clause.statements) {
     if (ts8.isReturnStatement(stmt) && stmt.expression) {
@@ -8812,6 +8990,23 @@ var REACTIVE_BINDING_KINDS = new Set([
 function isReactiveOrigin(origin) {
   return origin.freeRefs?.some((r) => REACTIVE_BINDING_KINDS.has(r.kind)) ?? false;
 }
+function tsxSourceText(raw) {
+  return raw;
+}
+function preambleAnalysisText(p) {
+  let out = "";
+  for (const seg of p.segments)
+    if (seg.kind === "js")
+      out += seg.text;
+  return out;
+}
+function preambleAnalysisTemplateText(p) {
+  let out = "";
+  for (const seg of p.segments)
+    if (seg.kind === "js")
+      out += seg.templateText ?? seg.text;
+  return out;
+}
 var AttrValueOf = {
   literal(value) {
     return { kind: "literal", value };
@@ -10051,8 +10246,13 @@ function attachParsedExpressions(node, analyzer, bound = EMPTY_BOUND) {
         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);
+      }
+      for (const seg of node.preamble?.segments ?? []) {
+        if (seg.kind === "jsx")
+          attachParsedExpressions(seg.ir, analyzer, loopBound);
       }
       break;
     }
@@ -10687,74 +10887,78 @@ function transformMultiReturnJsxFunctionCall(callExpr, info, ctx) {
   ctx.analyzer.getJS = substitutedGetJS;
   try {
     const loc = getSourceLocation(callExpr, ctx.sourceFile, ctx.filePath);
-    const nullExpr = {
-      type: "expression",
-      expr: "null",
-      typeInfo: { kind: "primitive", raw: "null", primitive: "null" },
-      reactive: false,
-      slotId: null,
-      loc,
-      origin: { phase: "tick", scope: "template", effect: "pure", freeRefs: [] }
-    };
-    let result = info.fallback ? transformNode(info.fallback, ctx) ?? nullExpr : nullExpr;
-    for (let i = info.branches.length - 1;i >= 0; i--) {
-      const branch = info.branches[i];
-      let conditionText;
-      if (info.switchDiscriminant) {
-        const discText = substitutedGetJS(info.switchDiscriminant);
-        const caseText = substitutedGetJS(branch.condition);
-        conditionText = `${discText} === ${caseText}`;
-      } else {
-        conditionText = substitutedGetJS(branch.condition);
-      }
-      const env = makeBindingEnv(ctx);
-      const caseFreeRefs = resolveFreeRefs(branch.condition, env);
-      const discFreeRefs = info.switchDiscriminant ? resolveFreeRefs(info.switchDiscriminant, env) : [];
-      const conditionOrigin = {
-        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;
-      let templateCondition;
-      if (info.switchDiscriminant) {
-        const discRewritten = rewriteBarePropRefs2(substitutedGetJS(info.switchDiscriminant), info.switchDiscriminant, ctx);
-        const caseRewritten = rewriteBarePropRefs2(substitutedGetJS(branch.condition), branch.condition, ctx);
-        const discPart = discRewritten ?? substitutedGetJS(info.switchDiscriminant);
-        const casePart = caseRewritten ?? substitutedGetJS(branch.condition);
-        templateCondition = `${discPart} === ${casePart}`;
-      } else {
-        templateCondition = rewriteBarePropRefs2(conditionText, branch.condition, ctx);
-      }
-      const conditional = {
-        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;
+    return foldMultiReturnBranches(info, ctx, loc, substitutedGetJS);
   } finally {
     ctx.getJS = originalCtxGetJS;
     ctx.analyzer.getJS = originalAnalyzerGetJS;
   }
 }
+function foldMultiReturnBranches(info, ctx, loc, getText) {
+  const nullExpr = {
+    type: "expression",
+    expr: "null",
+    typeInfo: { kind: "primitive", raw: "null", primitive: "null" },
+    reactive: false,
+    slotId: null,
+    loc,
+    origin: { phase: "tick", scope: "template", effect: "pure", freeRefs: [] }
+  };
+  let result = info.fallback ? transformNode(info.fallback, ctx) ?? nullExpr : nullExpr;
+  for (let i = info.branches.length - 1;i >= 0; i--) {
+    const branch = info.branches[i];
+    const caseConds = info.switchDiscriminant ? [branch.condition, ...branch.extraCaseConditions ?? []] : [branch.condition];
+    let conditionText;
+    if (info.switchDiscriminant) {
+      const discText = getText(info.switchDiscriminant);
+      conditionText = caseConds.map((c) => `(${discText}) === (${getText(c)})`).join(" || ");
+    } else {
+      conditionText = getText(branch.condition);
+    }
+    const env = makeBindingEnv(ctx);
+    const caseFreeRefs = caseConds.flatMap((c) => resolveFreeRefs(c, env));
+    const discFreeRefs = info.switchDiscriminant ? resolveFreeRefs(info.switchDiscriminant, env) : [];
+    const conditionOrigin = {
+      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;
+    let templateCondition;
+    if (info.switchDiscriminant) {
+      const discRewritten = rewriteBarePropRefs2(getText(info.switchDiscriminant), info.switchDiscriminant, ctx);
+      const discPart = discRewritten ?? getText(info.switchDiscriminant);
+      templateCondition = caseConds.map((c) => {
+        const casePart = rewriteBarePropRefs2(getText(c), c, ctx) ?? getText(c);
+        return `(${discPart}) === (${casePart})`;
+      }).join(" || ");
+    } else {
+      templateCondition = rewriteBarePropRefs2(conditionText, branch.condition, ctx);
+    }
+    const conditional = {
+      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(node, ctx) {
   const condition = ctx.getJS(node.condition);
   const conditionOrigin = {
@@ -11551,6 +11755,87 @@ function checkLoopKey(callback, ctx, isNested) {
     return;
   }
 }
+function flatMapProjectionCall(body) {
+  let expr;
+  if (ts11.isBlock(body)) {
+    const real = body.statements;
+    if (real.length !== 1 || !ts11.isReturnStatement(real[0]) || !real[0].expression)
+      return null;
+    expr = real[0].expression;
+  } else {
+    expr = body;
+  }
+  while (ts11.isParenthesizedExpression(expr))
+    expr = expr.expression;
+  if (!ts11.isCallExpression(expr))
+    return null;
+  if (!getMapLikeMethod(expr))
+    return null;
+  const cb = expr.arguments[0];
+  if (!cb || !ts11.isArrowFunction(cb) && !ts11.isFunctionExpression(cb))
+    return null;
+  for (const p of cb.parameters) {
+    if (!ts11.isIdentifier(p.name))
+      return null;
+  }
+  let innerBody = cb.body;
+  if (ts11.isBlock(innerBody)) {
+    const ret = innerBody.statements.find((s) => ts11.isReturnStatement(s) && s.expression != null);
+    if (innerBody.statements.length !== 1 || !ret?.expression)
+      return null;
+    innerBody = ret.expression;
+  }
+  while (ts11.isParenthesizedExpression(innerBody))
+    innerBody = innerBody.expression;
+  const isElementish = (n) => {
+    let m = n;
+    while (ts11.isParenthesizedExpression(m))
+      m = m.expression;
+    if (ts11.isJsxElement(m) || ts11.isJsxSelfClosingElement(m))
+      return leafIsWirelessElement(m);
+    if (ts11.isConditionalExpression(m))
+      return isElementish(m.whenTrue) && isElementish(m.whenFalse);
+    return false;
+  };
+  if (!isElementish(innerBody))
+    return null;
+  return expr;
+}
+function leafIsWirelessElement(el) {
+  let ok = true;
+  const visit2 = (n) => {
+    if (!ok)
+      return;
+    if (ts11.isJsxOpeningElement(n) || ts11.isJsxSelfClosingElement(n)) {
+      const tagNode = n.tagName;
+      const isIntrinsic = ts11.isIdentifier(tagNode) ? !/^[A-Z]/.test(tagNode.text) : ts11.isJsxNamespacedName(tagNode);
+      if (!isIntrinsic) {
+        ok = false;
+        return;
+      }
+      for (const attr of n.attributes.properties) {
+        if (ts11.isJsxSpreadAttribute(attr)) {
+          ok = false;
+          return;
+        }
+        if (ts11.isJsxAttribute(attr)) {
+          const name = attr.name.getText();
+          if (/^on[A-Z]/.test(name)) {
+            ok = false;
+            return;
+          }
+        }
+      }
+    }
+    if (ts11.isCallExpression(n) && getMapLikeMethod(n) && containsJsxInExpression(n)) {
+      ok = false;
+      return;
+    }
+    ts11.forEachChild(n, visit2);
+  };
+  visit2(el);
+  return ok;
+}
 function loopBodyIsMultiRoot(children) {
   const real = children.filter((c) => !(c.type === "text" && typeof c.value === "string" && !c.value.trim()));
   if (real.length === 0)
@@ -11596,6 +11881,7 @@ function extractItemConditionalKey(cond) {
 }
 function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
   const isNested = ctx.loopParams.size > 0;
+  const diagCountAtEntry = ctx.analyzer.errors.length;
   const depth = ctx.loopDepth;
   const propAccess = node.expression;
   const mapSource = propAccess.expression;
@@ -11605,9 +11891,7 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
   let filterPredicate;
   let sortComparator;
   let chainOrder;
-  let mapPreamble;
-  let templateMapPreamble;
-  let typedMapPreamble;
+  let preamble;
   let iterationShape;
   let objectIteration;
   const setArray = (node2) => {
@@ -11637,7 +11921,7 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
     const innerFilter = isFilterCall(sortInfo.array);
     const sortExtraction = extractSortComparator(sortInfo.callback, sortInfo.method, ctx);
     if (isClientOnly || !sortExtraction.result) {
-      if (!isClientOnly && sortExtraction.unsupportedReason) {
+      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), {
           message: `Expression cannot be compiled to marked template: ${sortExtraction.unsupportedReason}`,
           suggestion: {
@@ -11652,7 +11936,7 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
         chainOrder = "filter-sort";
         const filterExtraction = extractFilterPredicate(innerFilter.callback, ctx);
         if (isClientOnly || !filterExtraction.result) {
-          if (!isClientOnly && filterExtraction.unsupportedReason) {
+          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), {
               message: `Expression cannot be compiled to marked template: ${filterExtraction.unsupportedReason}`,
               suggestion: {
@@ -11675,7 +11959,7 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
     const innerSort = isSortCall(filterInfo.array);
     const filterExtraction = extractFilterPredicate(filterInfo.callback, ctx);
     if (isClientOnly || !filterExtraction.result) {
-      if (!isClientOnly && filterExtraction.unsupportedReason) {
+      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), {
           message: `Expression cannot be compiled to marked template: ${filterExtraction.unsupportedReason}`,
           suggestion: {
@@ -11690,7 +11974,7 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
         chainOrder = "sort-filter";
         const sortExtraction = extractSortComparator(innerSort.callback, innerSort.method, ctx);
         if (isClientOnly || !sortExtraction.result) {
-          if (!isClientOnly && sortExtraction.unsupportedReason) {
+          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), {
               message: `Expression cannot be compiled to marked template: ${sortExtraction.unsupportedReason}`,
               suggestion: {
@@ -11805,7 +12089,24 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
     } else if (method === "flatMap" && ts11.isArrayLiteralExpression(body)) {
       children = transformArrayLiteralChildren(body, ctx);
     } else if (ts11.isBlock(body)) {
-      const returnStmt = body.statements.find((s) => ts11.isReturnStatement(s) && s.expression != null);
+      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) {
+          preamble = preambleFromValueStatements(pre, ctx);
+          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"
+              }
+            }));
+          }
+        }
+      }
+      const returnStmt = children.length === 0 ? body.statements.find((s) => ts11.isReturnStatement(s) && s.expression != null) : undefined;
       if (returnStmt && returnStmt.expression) {
         let returnExpr = returnStmt.expression;
         while (ts11.isParenthesizedExpression(returnExpr)) {
@@ -11817,41 +12118,84 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
             children = [transformed];
           }
         }
-        const preambleStmts = [];
-        const templatePreambleStmts = [];
-        const typedPreambleStmts = [];
-        let hasTypeDiff = false;
-        let hasTemplateDiff = false;
+        let jsxPreambleStmt;
         for (const stmt of body.statements) {
           if (stmt === returnStmt)
             break;
-          const js = ctx.getJS(stmt);
-          const tjs = ctx.getTemplateJS(stmt);
-          const ts12 = stmt.getText(ctx.sourceFile);
-          preambleStmts.push(js.endsWith(";") ? js : js + ";");
-          templatePreambleStmts.push(tjs.endsWith(";") ? tjs : tjs + ";");
-          typedPreambleStmts.push(ts12.endsWith(";") ? ts12 : ts12 + ";");
-          if (js !== ts12)
-            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) {
+          const jsRuntime = isClientOnly || (ctx.analyzer.acceptsCallbackBody?.("map") ?? false);
+          if (children.length === 0) {
+            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) {
+              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 = [];
+          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);
           }
         }
       }
-      if (method === "flatMap" && children.length === 0) {
+      if (method === "flatMap" && children.length === 0 && !flatMapProjectionCall(body)) {
         flatMapCallback = buildFlatMapCallback(callback, body, ctx);
       }
     } else {
       tryTransformRenderableBody(body);
     }
+    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];
+        }
+      }
+    }
+    if (method === "flatMap" && children.length === 0 && !flatMapCallback && !ts11.isBlock(body)) {
+      flatMapCallback = buildFlatMapCallback(callback, body, ctx);
+    }
+    if (flatMapCallback)
+      preamble = undefined;
+    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"
+        }
+      }));
+    }
     if (paramBindings) {
       for (const b of paramBindings)
         ctx.loopParams.delete(b.name);
@@ -11863,6 +12207,16 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
     ctx.loopDepth--;
   }
   if (children.length === 0 && !flatMapCallback) {
+    const cb = node.arguments[0];
+    const cbBody = cb && (ts11.isArrowFunction(cb) || ts11.isFunctionExpression(cb)) ? cb.body : undefined;
+    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;
   }
   if (ts11.isArrowFunction(node.arguments[0]) && children.length > 0) {
@@ -11871,6 +12225,31 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
   const itemConditional = children.length > 0 ? loopBodyItemConditional(children) : null;
   const bodyIsItemConditional = itemConditional !== null;
   const key = bodyIsItemConditional ? extractItemConditionalKey(itemConditional) : children.length > 0 ? extractLoopKey(children[0]) : null;
+  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})."
+        }
+      }));
+    }
+  }
+  if (preamble && preamble.builderNames.length > 0) {
+    flagArrayChildExpressions(children, new Set(preamble.builderNames));
+  }
+  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."
+      }
+    }));
+    preamble = undefined;
+  }
   let childComponent;
   if (children.length === 1 && children[0].type === "component") {
     const comp = children[0];
@@ -11890,6 +12269,7 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
   const hasCalls = exprHasFunctionCalls(arrayExpr);
   const isDirectPropArray = method !== "flatMap" && isArrayExprDirectPropRef(arrayExpr, ctx);
   const isStaticArray = !isSignalOrMemoArray(array, ctx) && !isDirectPropArray && !hasCalls && !objectIteration;
+  const preambleRegions = preamble && !isStaticArray ? collectPreambleRegions(children, new Set(preamble.declaredNames), ctx) : undefined;
   const nestedComponents = collectNestedComponents(children).filter((c) => c.name !== childComponent?.name);
   return {
     type: "loop",
@@ -11919,11 +12299,10 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
     objectIteration,
     depth,
     clientOnly: isClientOnly || undefined,
-    mapPreamble,
-    templateMapPreamble,
+    preamble,
+    preambleRegions: preambleRegions && preambleRegions.length > 0 ? preambleRegions : undefined,
     paramType,
     indexType,
-    typedMapPreamble,
     paramBindings,
     arrayFreeIdentifiers: extractFreeIdentifiersFromNode(arrayExpr),
     flatMapCallback,
@@ -11959,47 +12338,281 @@ function containsJsx(node) {
 function buildFlatMapCallback(callback, body, ctx) {
   if (!containsJsx(body))
     return;
-  const fragments = [];
-  const sourceText = ctx.sourceFile.text;
-  const bodyStart = body.getStart(ctx.sourceFile);
-  const bodyEnd = body.getEnd();
-  const bodyText = sourceText.slice(bodyStart, bodyEnd);
-  const jsxNodes = [];
-  function collectJsx(n) {
+  const leafSpans = [];
+  const leafIrs = [];
+  let refusalNode;
+  const collectJsx = (n, underTemplate) => {
     if (ts11.isJsxElement(n) || ts11.isJsxSelfClosingElement(n) || ts11.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, ctx);
+      leafIrs.push(ir ?? { type: "text", value: "", loc: getSourceLocation(n, ctx.sourceFile, ctx.filePath) });
       return;
     }
-    n.forEachChild(collectJsx);
-  }
-  collectJsx(body);
-  if (jsxNodes.length === 0)
+    const inTemplate = underTemplate || ts11.isTemplateExpression(n) || ts11.isTaggedTemplateExpression(n);
+    n.forEachChild((c) => collectJsx(c, inTemplate));
+  };
+  collectJsx(body, false);
+  if (leafSpans.length === 0)
     return;
-  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, ctx);
-    fragments.push({
-      placeholder,
-      ir: ir ?? { type: "text", value: "", loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath) }
-    });
+  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;
+  }
+  for (const leafIr of leafIrs) {
+    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;
+    }
+    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;
+    }
   }
-  compiledBody += bodyText.slice(lastEnd);
+  const pieces = reconstructAsSegments(body, ctx.sourceFile, ctx.analyzer.typeExcludeRanges, leafSpans);
+  const segments = pieces.map((piece) => {
+    if ("marker" in piece)
+      return { kind: "jsx", ir: leafIrs[piece.marker] };
+    const tpl = rewriteBarePropRefs2(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))
+  };
+}
+function flatMapLeafNeedsWiring(ir) {
+  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;
+  }
+}
+function preambleFragmentNeedsWiring(ir) {
+  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(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;
+  }
+}
+function flagArrayChildExpressions(nodes, declared) {
+  for (const node of nodes) {
+    switch (node.type) {
+      case "expression": {
+        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;
+    }
+  }
+}
+function collectPreambleRegions(nodes, declared, ctx) {
+  const regions = [];
+  const visit2 = (list) => {
+    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":
+          visit2(node.children);
+          break;
+        case "conditional":
+          visit2([node.whenTrue, ...node.whenFalse ? [node.whenFalse] : []]);
+          break;
+      }
+    }
+  };
+  visit2(nodes);
+  return regions;
+}
+function collectBindingNames(name, out) {
+  if (ts11.isIdentifier(name)) {
+    out.add(name.text);
+    return;
+  }
+  for (const el of name.elements) {
+    if (ts11.isBindingElement(el))
+      collectBindingNames(el.name, out);
+  }
+}
+function collectPreambleDeclaredNames(stmt, out) {
+  if (ts11.isVariableStatement(stmt)) {
+    for (const decl of stmt.declarationList.declarations) {
+      collectBindingNames(decl.name, out);
+    }
+  } else if (ts11.isFunctionDeclaration(stmt) && stmt.name) {
+    out.add(stmt.name.text);
+  }
+}
+function preambleFromValueStatements(statements, ctx) {
+  const segments = [];
+  const typedParts = [];
+  const declared = new Set;
+  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],
+    builderNames: []
+  };
+}
+function trimPreambleSegments(segments) {
+  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;
+}
+function buildPreambleSegments(statements, returnStmt, ctx) {
+  const segments = [];
+  const typedParts = [];
+  const declared = new Set;
+  const builders = new Set;
+  let refusalNode;
+  const recordBuilderTarget = (leaf, stmt) => {
+    for (let n = leaf.parent;n && n !== stmt.parent; n = n.parent) {
+      if (ts11.isCallExpression(n) && ts11.isPropertyAccessExpression(n.expression) && (n.expression.name.text === "push" || n.expression.name.text === "unshift") && ts11.isIdentifier(n.expression.expression)) {
+        builders.add(n.expression.expression.text);
+        return;
+      }
+      if (ts11.isVariableDeclaration(n) && ts11.isIdentifier(n.name)) {
+        builders.add(n.name.text);
+        return;
+      }
+    }
+  };
+  for (const stmt of statements) {
+    if (stmt === returnStmt)
+      break;
+    collectPreambleDeclaredNames(stmt, declared);
+    const leafSpans = [];
+    const leafIrs = [];
+    const collect = (n, underTemplate) => {
+      if (ts11.isJsxElement(n) || ts11.isJsxSelfClosingElement(n) || ts11.isJsxFragment(n)) {
+        if (underTemplate)
+          refusalNode ??= n;
+        recordBuilderTarget(n, stmt);
+        leafSpans.push({ start: n.getStart(ctx.sourceFile), end: n.getEnd() });
+        const ir = transformNode(n, ctx);
+        if (ir && preambleFragmentNeedsWiring(ir))
+          refusalNode ??= n;
+        leafIrs.push(ir ?? { type: "text", value: "", loc: getSourceLocation(n, ctx.sourceFile, ctx.filePath) });
+        return;
+      }
+      const inTemplate = underTemplate || ts11.isTemplateExpression(n) || ts11.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 {
+        const tpl = rewriteBarePropRefs2(piece.js, stmt, ctx);
+        segments.push(tpl !== undefined && tpl !== piece.js ? { kind: "js", text: piece.js, templateText: tpl } : { kind: "js", text: piece.js });
+      }
+    }
+    const sep2 = raw0.endsWith(";") ? " " : "; ";
+    segments.push({ kind: "js", text: sep2 });
+  }
+  return {
+    preamble: {
+      segments: trimPreambleSegments(segments),
+      ssrText: tsxSourceText(typedParts.join(" ")),
+      declaredNames: [...declared],
+      builderNames: [...builders]
+    },
+    refusalNode
   };
 }
 function collectNestedComponents(nodes) {
@@ -13258,6 +13871,8 @@ function collectLoopChildReactiveTexts(node, ctx, loopParam, loopParamBindings,
     expression: ({ node: n, scope: insideConditional }) => {
       if (!n.slotId)
         return;
+      if (n.preambleRegion)
+        return;
       const originFreeIds = freeIdsFromRefs(n.origin?.freeRefs);
       const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds);
       const reactive = classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind !== "none" || decideWrapFromAstFlags(n).wrap;
@@ -13642,7 +14257,7 @@ function collectInnerLoops(nodes, siblingOffsets, outerLoopParam, ctx, options)
           objectIteration: n.objectIteration,
           containerSlotId: scope.parentSlotId,
           template,
-          mapPreamble: n.mapPreamble,
+          preamble: n.preamble,
           refsOuterParam: refsOuter,
           childComponents,
           insideConditional: !flat && scope.insideCond ? true : undefined,
@@ -13813,10 +14428,13 @@ function collectElements(node, ctx, siblingOffsets, insideConditional = false) {
     loop: ({ node: l, scope: inCond }) => {
       if (!l.slotId || inCond)
         return;
+      const projectionInner = l.method === "flatMap" && l.children.length === 1 && l.children[0].type === "loop" ? l.children[0] : undefined;
       const childHandlers = [];
-      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) {
         for (const prop of l.childComponent.props) {
@@ -13827,7 +14445,7 @@ function collectElements(node, ctx, siblingOffsets, insideConditional = false) {
           }
         }
       }
-      const { useElementReconciliation, innerLoops } = decideLoopRendering(l, siblingOffsets, ctx);
+      const { useElementReconciliation, innerLoops } = projectionInner ? { useElementReconciliation: false, innerLoops: undefined } : decideLoopRendering(l, siblingOffsets, ctx);
       let template = "";
       let staticItemTemplate;
       let skeletonTemplate;
@@ -13837,7 +14455,7 @@ function collectElements(node, ctx, siblingOffsets, insideConditional = false) {
         if (l.isStaticArray && l.children[0]) {
           staticItemTemplate = irToHtmlTemplate(l.children[0], buildRestSpreadNames(ctx), 0, undefined, undefined, true);
         }
-      } else if (l.children[0]) {
+      } else if (l.children[0] && !projectionInner) {
         const loopParamSpec = [{ param: l.param, bindings: l.paramBindings }];
         template = useElementReconciliation ? irToPlaceholderTemplate(l.children[0], buildRestSpreadNames(ctx), 0, loopParamSpec) : irToHtmlTemplate(l.children[0], buildRestSpreadNames(ctx), 0, loopParamSpec);
         if (l.isStaticArray) {
@@ -13889,7 +14507,17 @@ function collectElements(node, ctx, siblingOffsets, insideConditional = false) {
           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
       });
     },
     component: ({ node: c, descend, descendJsxChildren }) => {
@@ -14046,15 +14674,18 @@ function collectBranchLoops(node, ctx, siblingOffsets) {
       const containerSlot = parentSlotId ?? n.slotId;
       if (!containerSlot)
         return;
-      const { useElementReconciliation, innerLoops: innerLoopsCollected } = decideLoopRendering(n, siblingOffsets, undefined);
+      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);
       let childTemplate;
       const branchLoopParamSpec = [{ param: n.param, bindings: n.paramBindings }];
-      if (useElementReconciliation && n.children[0]) {
+      if (projectionInner) {
+        childTemplate = "";
+      } 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("");
       }
-      const branchBindings = ctx ? collectLoopChildBindings(n.children, ctx, siblingOffsets, n.param, n.paramBindings) : emptyLoopChildBindings();
+      const branchBindings = ctx && !projectionInner ? collectLoopChildBindings(n.children, ctx, siblingOffsets, n.param, n.paramBindings) : emptyLoopChildBindings();
       loops.push({
         kind: "branch",
         array: n.array,
@@ -14070,7 +14701,8 @@ function collectBranchLoops(node, ctx, siblingOffsets) {
         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,
@@ -14084,7 +14716,16 @@ function collectBranchLoops(node, ctx, siblingOffsets) {
           paramB: n.sortComparator.paramB,
           raw: n.sortComparator.raw
         } : undefined,
-        chainOrder: n.chainOrder
+        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
       });
     }
   });
@@ -14346,8 +14987,8 @@ function buildReferencesGraph(ctx, irRoot) {
       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");
     for (const attr of elem.bindings.reactiveAttrs) {
       addExprEdges(ROOT_SOURCE, attr.expression, "template-closure");
     }
@@ -14457,8 +15098,15 @@ function buildReferencesGraph(ctx, irRoot) {
         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");
+      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);
@@ -14636,6 +15284,8 @@ var RUNTIME_IMPORT_CANDIDATES = [
   "getLoopNodes",
   "mapArray",
   "mapArrayAnchored",
+  "patchLeaf",
+  "patchSlotRange",
   "createDisposableEffect",
   "createComponent",
   "renderChild",
@@ -16567,7 +17217,7 @@ function nestedLoopReferencesIndex(inner, comps, events) {
     if (exprRefs(a.expression, a.freeIdentifiers))
       return true;
   }
-  if (inner.mapPreamble && extractFreeIdentifiersFromStatementText(inner.mapPreamble).has(index))
+  if (inner.preamble && extractFreeIdentifiersFromStatementText(preambleAnalysisText(inner.preamble)).has(index))
     return true;
   if (inner.template && extractFreeIdentifiersFromTemplateText(inner.template).has(index))
     return true;
@@ -16638,6 +17288,15 @@ function destructureLoopParam(param, paramBindings) {
   }
   return { head: param, unwrap: "" };
 }
+function buildPreambleRegionPlans(regions, loopParam, loopParamBindings) {
+  if (!regions || regions.length === 0)
+    return [];
+  return regions.map((r) => {
+    const wrapped = wrapLoopParamAsAccessor(r.expr, loopParam, loopParamBindings);
+    const valueExpr = r.joinArrayChild ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')` : `escapeText(${wrapped})`;
+    return { slotId: r.slotId, valueExpr };
+  });
+}
 function buildComponentPropsExpr2(comp, loopParam, loopParamBindings) {
   const wrap = loopParam ? (expr) => wrapLoopParamAsAccessor(expr, loopParam, loopParamBindings) : (expr) => expr;
   const entries = comp.props.map((p) => {
@@ -16722,6 +17381,11 @@ function emitComponentAndEventSetup(ls, indent, elVar, comps, events, loopParam,
 }
 
 // src/ir-to-client-js/plan/build-static-array-child-init.ts
+function staticPreludeStatements(preamble) {
+  return preamble ? [renderPreamble(preamble, {
+    renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
+  })] : [];
+}
 function buildStaticArrayChildInitsPlan(ctx) {
   const plans = [];
   for (const elem of ctx.loopElements) {
@@ -16759,7 +17423,7 @@ function buildSingleCompPlan(elem, childComponent) {
     arrayExpr: elem.array,
     param: elem.param,
     indexParam: elem.index || "__idx",
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     propsExpr: buildStaticPropsExpr(props)
   };
 }
@@ -16774,7 +17438,7 @@ function buildOuterNestedPlan(elem, comp) {
     param: elem.param,
     indexParam,
     offsetExpr: buildLoopChildIndexExpr(indexParam, elem.offset),
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     propsExpr: buildStaticPropsExpr(comp.props)
   };
 }
@@ -16793,13 +17457,13 @@ function buildInnerLoopNestedPlan(elem, innerLoop, innerComps) {
     outerParam: elem.param,
     outerIndexParam,
     outerOffsetExpr: buildLoopChildIndexExpr(outerIndexParam, elem.offset),
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     innerContainerSlotId: innerLoop.containerSlotId ?? null,
     innerArrayExpr: innerLoop.array,
     innerParam: innerLoop.param,
     innerIndexParam,
     innerOffsetExpr: buildLoopChildIndexExpr(innerIndexParam, innerLoop.offset),
-    innerPreludeStatements: innerLoop.mapPreamble ? [innerLoop.mapPreamble] : [],
+    innerPreludeStatements: staticPreludeStatements(innerLoop.preamble),
     depth: innerLoop.depth,
     comps
   };
@@ -16816,11 +17480,11 @@ function buildComponentRootedInnerLoopPlan(elem, innerLoop, innerComps) {
     outerArrayExpr: elem.array,
     outerParam: elem.param,
     outerIndexParam: elem.index,
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     innerArrayExpr: innerLoop.array,
     innerParam: innerLoop.param,
     innerIndexParam: innerLoop.index,
-    innerPreludeStatements: innerLoop.mapPreamble ? [innerLoop.mapPreamble] : [],
+    innerPreludeStatements: staticPreludeStatements(innerLoop.preamble),
     depth: innerLoop.depth,
     comps
   };
@@ -17389,7 +18053,7 @@ function buildInnerLoopsPlan(args) {
     const containerExpr = inner.containerSlotId ? `qsa(${parentElVar}, '[bf="${inner.containerSlotId}"]')` : parentElVar;
     const refsParent = !!outerLoopParam && (inner.arrayFreeIdentifiers?.has(outerLoopParam) ?? false);
     const useReactive = refsParent && !!inner.template;
-    const emit = useReactive ? buildReactiveEmit(inner, level, wrapOuter, uidSuffix) : buildStaticEmit(inner, level, uidSuffix);
+    const emit = useReactive ? buildReactiveEmit(inner, level, wrapOuter, uidSuffix, outerLoopParam, outerLoopParamBindings) : buildStaticEmit(inner, level, uidSuffix);
     const arrayExpr = useReactive ? wrapOuter(inner.array) : inner.array;
     const childLevelsPlan = childLevels.length > 0 ? buildInnerLoopsPlan({
       levels: childLevels,
@@ -17415,7 +18079,7 @@ function buildInnerLoopsPlan(args) {
   }
   return plan;
 }
-function buildReactiveEmit(inner, level, wrapOuter, uidSuffix) {
+function buildReactiveEmit(inner, level, wrapOuter, uidSuffix, outerLoopParam, outerLoopParamBindings) {
   const wrapInner = (expr) => wrapLoopParamAsAccessor(expr, inner.param, inner.paramBindings);
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(inner.param, inner.paramBindings);
   const wrappedKey = inner.key ? wrapLoopParamAsAccessor(inner.key, inner.param, inner.paramBindings) : null;
@@ -17467,8 +18131,16 @@ function buildReactiveEmit(inner, level, wrapOuter, uidSuffix) {
     preludeStatements.push(indexAlias);
   if (paramUnwrap)
     preludeStatements.push(paramUnwrap);
-  if (inner.mapPreamble)
-    preludeStatements.push(wrapInner(wrapOuter(inner.mapPreamble)));
+  if (inner.preamble) {
+    const leafLoopParams = outerLoopParam ? [
+      { param: outerLoopParam, bindings: outerLoopParamBindings },
+      { param: inner.param, bindings: inner.paramBindings }
+    ] : [{ param: inner.param, bindings: inner.paramBindings }];
+    preludeStatements.push(renderPreamble(inner.preamble, {
+      transformJs: (t) => wrapInner(wrapOuter(t)),
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, leafLoopParams, undefined, true)
+    }));
+  }
   const childRefs = buildChildRefBindings(inner.bindings.refs, inner.param, inner.paramBindings);
   return {
     mode: "reactive",
@@ -17490,8 +18162,11 @@ function buildStaticEmit(inner, level, uidSuffix) {
   const indexAlias = nestedLoopIndexAlias(inner, `__innerIdx${uidSuffix}`, inner.param, level.comps, level.events);
   if (indexAlias)
     preludeStatements.push(indexAlias);
-  if (inner.mapPreamble)
-    preludeStatements.push(inner.mapPreamble);
+  if (inner.preamble) {
+    preludeStatements.push(renderPreamble(inner.preamble, {
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
+    }));
+  }
   return {
     mode: "static",
     rawKey: inner.key ?? null,
@@ -17511,6 +18186,7 @@ function buildTopLevelCompositePlan(elem, profileComponentName) {
   const outerCompsByDepth = nestedComps.filter((c) => !c.loopDepth || c.loopDepth === 0);
   return {
     kind: "composite",
+    rowConstruction: "string-template",
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     arrayExpr: buildChainedArrayExpr(elem),
@@ -17518,7 +18194,10 @@ function buildTopLevelCompositePlan(elem, profileComponentName) {
     paramHead,
     paramUnwrap,
     indexParam: elem.index || "__idx",
-    mapPreambleWrapped: elem.mapPreamble ? wrap(elem.mapPreamble) : "",
+    mapPreambleWrapped: elem.preamble ? renderPreamble(elem.preamble, {
+      transformJs: wrap,
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true)
+    }) : "",
     template: elem.template,
     outerComps: filterCondCompsOut(outerCompsByDepth, elem.bindings.conditionals),
     outerEvents: elem.bindings.events.filter((ev) => ev.nestedLoops.length === 0),
@@ -17557,6 +18236,7 @@ function buildBranchCompositePlan(loop, cv, profileComponentName) {
   const outerCompsByDepth = nestedComps.filter((c) => !c.loopDepth || c.loopDepth === 0);
   return {
     kind: "composite",
+    rowConstruction: "string-template",
     containerVar: `__loop_${cv}`,
     markerId: loop.markerId,
     arrayExpr: buildChainedArrayExpr(loop),
@@ -17564,7 +18244,10 @@ function buildBranchCompositePlan(loop, cv, profileComponentName) {
     paramHead,
     paramUnwrap,
     indexParam: loop.index || "__idx",
-    mapPreambleWrapped: loop.mapPreamble ? wrap(loop.mapPreamble) : "",
+    mapPreambleWrapped: loop.preamble ? renderPreamble(loop.preamble, {
+      transformJs: wrap,
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true)
+    }) : "",
     template: loop.template,
     outerComps: filterCondCompsOut(outerCompsByDepth, loop.bindings.conditionals),
     outerEvents: childEvents.filter((ev) => ev.nestedLoops.length === 0),
@@ -17627,7 +18310,10 @@ function buildDynamicLoopDelegationPlan(elem, profileComponentName) {
       paramBindings: elem.paramBindings,
       key: elem.key,
       index: elem.index,
-      mapPreamble: elem.mapPreamble ?? null
+      mapPreamble: elem.preamble ? renderPreamble(elem.preamble, {
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
+      }) : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? []
     })
   };
 }
@@ -17643,7 +18329,10 @@ function buildBranchLoopDelegationPlan(loop, cv, profileComponentName) {
       paramBindings: loop.paramBindings,
       key: loop.key,
       index: loop.index,
-      mapPreamble: loop.mapPreamble ?? null
+      mapPreamble: loop.preamble ? renderPreamble(loop.preamble, {
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
+      }) : null,
+      mapPreambleDeclaredNames: loop.preamble?.declaredNames ?? []
     })
   };
 }
@@ -17657,7 +18346,10 @@ function buildStaticArrayDelegationPlan(elem, profileComponentName) {
       kind: "static-index",
       arrayExpr: buildChainedArrayExpr(elem),
       param: elem.param,
-      mapPreamble: elem.mapPreamble ?? null,
+      mapPreamble: elem.preamble ? renderPreamble(elem.preamble, {
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
+      }) : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? [],
       offset: elem.offset ?? null,
       indexParam: elem.index ?? null
     }
@@ -17674,6 +18366,7 @@ function buildKeyedOrIndexLookup(args) {
       paramBindings: args.paramBindings,
       keyWithItem,
       mapPreamble: args.mapPreamble,
+      mapPreambleDeclaredNames: args.mapPreambleDeclaredNames,
       hasBindings,
       indexParam: args.index
     };
@@ -17683,6 +18376,7 @@ function buildKeyedOrIndexLookup(args) {
     arrayExpr: args.array,
     param: args.param,
     mapPreamble: args.mapPreamble,
+    mapPreambleDeclaredNames: args.mapPreambleDeclaredNames,
     hasBindings,
     indexParam: args.index
   };
@@ -17704,17 +18398,23 @@ function buildBranchLoopPlan(loop, profileComponentName) {
   }
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(loop.param, loop.paramBindings);
   const hasReactiveEffects = loop.bindings.reactiveAttrs.length > 0 || loop.bindings.reactiveTexts.length > 0 || loop.bindings.conditionals.length > 0;
+  const fm = loop.flatMapClient;
   const plan = {
     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",
-    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 ? buildReactiveEffectsPlan({
       attrs: loop.bindings.reactiveAttrs,
@@ -17726,6 +18426,7 @@ function buildBranchLoopPlan(loop, profileComponentName) {
     }) : 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
   };
@@ -18373,6 +19074,22 @@ function emitLoopChildRefs(lines, refs, opts) {
     lines.push(`${indent}if (${varName}) ${emitRefCall(ref.callback, varName)} }`);
   }
 }
+function emitPreambleRegionEffects(lines, regions, mapPreambleWrapped, opts) {
+  if (regions.length === 0)
+    return;
+  const { indent, elVar } = opts;
+  for (const region of regions) {
+    const v = varSlotId(region.slotId);
+    lines.push(`${indent}{ let __last_${v}`);
+    lines.push(`${indent}createEffect(() => {`);
+    if (mapPreambleWrapped)
+      lines.push(`${indent}  ${mapPreambleWrapped}`);
+    lines.push(`${indent}  const __html_${v} = ${region.valueExpr}`);
+    lines.push(`${indent}  if (__last_${v} === undefined) { __last_${v} = __html_${v}; return }`);
+    lines.push(`${indent}  if (__html_${v} !== __last_${v}) { __last_${v} = __html_${v}; patchSlotRange(${elVar}, '${region.slotId}', __html_${v}) }`);
+    lines.push(`${indent}}) }`);
+  }
+}
 function stringifyLoop(lines, plan) {
   switch (plan.kind) {
     case "static":
@@ -18414,8 +19131,24 @@ function stringifyPlainLoop(lines, plan, topIndent = "  ") {
     childRefs,
     bodyIsMultiRoot,
     anchored,
-    anchorKeyExpr
+    anchorKeyExpr,
+    preambleRegions
   } = plan;
+  if (plan.flatMapLeafItem) {
+    const loopBfIdArg = plan.profileLoopId ? `, ${JSON.stringify(plan.profileLoopId)}` : "";
+    lines.push(`${topIndent}mapArray(() => ${arrayExpr}, ${containerVar}, ${keyFn}, (__bfD, ${indexParam}, __existing) => {`);
+    lines.push(`${topIndent}  let __el = __existing`);
+    lines.push(`${topIndent}  if (!__el) { const __tpl = document.createElement('template'); __tpl.innerHTML = __bfD().h; __el = __tpl.content.firstElementChild }`);
+    lines.push(`${topIndent}  let __last = __existing ? undefined : __bfD().h`);
+    lines.push(`${topIndent}  createEffect(() => {`);
+    lines.push(`${topIndent}    const __html = __bfD().h`);
+    lines.push(`${topIndent}    if (__last === undefined) { __last = __html; return }`);
+    lines.push(`${topIndent}    if (__html !== __last) { __last = __html; patchLeaf(__el, __html) }`);
+    lines.push(`${topIndent}  })`);
+    lines.push(`${topIndent}  return __el`);
+    lines.push(`${topIndent}}, '${markerId}'${loopBfIdArg})`);
+    return;
+  }
   if (anchored) {
     stringifyAnchoredLoop(lines, plan, topIndent, anchorKeyExpr);
     return;
@@ -18426,7 +19159,7 @@ function stringifyPlainLoop(lines, plan, topIndent = "  ") {
     emitHoistedTemplateDecl(lines, topIndent, tplVar, hoistedTpl);
   }
   const loopBfId = plan.profileLoopId ? `, ${JSON.stringify(plan.profileLoopId)}` : "";
-  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0) {
+  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0 && preambleRegions.length === 0) {
     const unwrapInline = paramUnwrap ? `${paramUnwrap} ` : "";
     const preamble = mapPreambleWrapped ? `${mapPreambleWrapped}; ` : "";
     const cloneExpr = hoistedTpl ? `return ${hoistedCloneExpr(tplVar, hoistedTpl)}` : emitTemplateCloneInline(template);
@@ -18474,6 +19207,7 @@ function stringifyPlainLoop(lines, plan, topIndent = "  ") {
     });
   }
   emitLoopChildRefs(lines, childRefs, { indent: bodyIndent, elVar: "__el", bodyIsMultiRoot, elementIndexBySlot: pathPlan?.elementIndexBySlot });
+  emitPreambleRegionEffects(lines, preambleRegions, mapPreambleWrapped, { indent: bodyIndent, elVar: "__el" });
   lines.push(`${bodyIndent}return __el`);
   lines.push(`${topIndent}}, '${markerId}'${loopBfId})`);
 }
@@ -18784,6 +19518,12 @@ function indexBindingLine(handler, indexParam, indexExpr) {
     return null;
   return `const ${indexParam} = ${indexExpr}`;
 }
+function preambleLineForHandler(mapPreamble, declaredNames, handler) {
+  if (!mapPreamble || declaredNames.length === 0)
+    return null;
+  const free = extractFreeIdentifiersFromText(handler);
+  return declaredNames.some((name) => free.has(name)) ? mapPreamble : null;
+}
 function stringifyEventDelegation(lines, plan) {
   const { containerVar, events, itemLookup, profileComponentName } = plan;
   const eventsByName = new Map;
@@ -18804,7 +19544,7 @@ function stringifyEventDelegation(lines, plan) {
     for (const ev of evs) {
       const childVar = varSlotId(ev.childSlotId);
       lines.push(`    const ${childVar}El = target.closest('[bf="${ev.childSlotId}"]')`);
-      lines.push(`    if (${childVar}El) {`);
+      lines.push(`    if (${childVar}El && ${containerVar}.contains(${childVar}El)) {`);
       const handlerCall = withTurn(`(${ev.handler.trim()})(__bfEvt)`, profileComponentName, ev.childSlotId, ev.eventName);
       switch (itemLookup.kind) {
         case "keyed":
@@ -18829,7 +19569,8 @@ function stringifyEventDelegation(lines, plan) {
   }
 }
 function emitKeyedLookup(ls, ev, handlerCall, lookup) {
-  const { arrayExpr, param, keyWithItem, mapPreamble, hasBindings, indexParam } = lookup;
+  const { arrayExpr, param, keyWithItem, mapPreamble, mapPreambleDeclaredNames, hasBindings, indexParam } = lookup;
+  const preambleLine = preambleLineForHandler(mapPreamble, mapPreambleDeclaredNames, ev.handler);
   if (ev.nestedLoops.length === 0) {
     const idxLine2 = indexBindingLine(ev.handler, indexParam, `${arrayExpr}.findIndex(item => String(${keyWithItem}) === key)`);
     ls.push(`      const li = ${varSlotId(ev.childSlotId)}El.closest('[${DATA_KEY}]')`);
@@ -18839,20 +19580,21 @@ function emitKeyedLookup(ls, ev, handlerCall, lookup) {
       ls.push(`        const __bfLoopItem = ${arrayExpr}.find(item => String(${keyWithItem}) === key)`);
       ls.push(`        if (__bfLoopItem) {`);
       ls.push(`          const ${param} = __bfLoopItem`);
-      if (mapPreamble)
-        ls.push(`          ${mapPreamble}`);
+      if (preambleLine)
+        ls.push(`          ${preambleLine}`);
       if (idxLine2)
         ls.push(`          ${idxLine2}`);
-      ls.push(`          ${handlerCall}`);
+      ls.push(`          ;${handlerCall}`);
       ls.push(`        }`);
     } else {
       ls.push(`        const ${param} = ${arrayExpr}.find(item => String(${keyWithItem}) === key)`);
-      if (mapPreamble)
-        ls.push(`        ${mapPreamble}`);
+      ls.push(`        if (${param}) {`);
+      if (preambleLine)
+        ls.push(`          ${preambleLine}`);
       if (idxLine2)
-        ls.push(`        if (${param}) { ${idxLine2}; ${handlerCall} }`);
-      else
-        ls.push(`        if (${param}) ${handlerCall}`);
+        ls.push(`          ${idxLine2}`);
+      ls.push(`          ;${handlerCall}`);
+      ls.push(`        }`);
     }
     ls.push(`      }`);
     return;
@@ -18879,16 +19621,18 @@ function emitKeyedLookup(ls, ev, handlerCall, lookup) {
   }
   const outerGuard = hasBindings ? "__bfLoopItem" : param;
   const allParams = [outerGuard, ...ev.nestedLoops.map((n) => n.param)];
-  if (mapPreamble)
-    ls.push(`      ${mapPreamble}`);
   const idxLine = indexBindingLine(ev.handler, indexParam, `${arrayExpr}.findIndex(item => String(${keyWithItem}) === outerKey)`);
+  ls.push(`      if (${allParams.join(" && ")}) {`);
+  if (preambleLine)
+    ls.push(`        ${preambleLine}`);
   if (idxLine)
-    ls.push(`      if (${allParams.join(" && ")}) { ${idxLine}; ${handlerCall} }`);
-  else
-    ls.push(`      if (${allParams.join(" && ")}) ${handlerCall}`);
+    ls.push(`        ${idxLine}`);
+  ls.push(`        ;${handlerCall}`);
+  ls.push(`      }`);
 }
 function emitDynamicIndexLookup(ls, ev, handlerCall, lookup) {
-  const { arrayExpr, param, mapPreamble, hasBindings, indexParam } = lookup;
+  const { arrayExpr, param, mapPreamble, mapPreambleDeclaredNames, hasBindings, indexParam } = lookup;
+  const preambleLine = preambleLineForHandler(mapPreamble, mapPreambleDeclaredNames, ev.handler);
   const idxLine = indexBindingLine(ev.handler, indexParam, "idx");
   ls.push(`      const li = ${varSlotId(ev.childSlotId)}El.closest('li, [bf-i]')`);
   ls.push(`      if (li && li.parentElement) {`);
@@ -18897,25 +19641,27 @@ function emitDynamicIndexLookup(ls, ev, handlerCall, lookup) {
     ls.push(`        const __bfLoopItem = ${arrayExpr}[idx]`);
     ls.push(`        if (__bfLoopItem) {`);
     ls.push(`          const ${param} = __bfLoopItem`);
-    if (mapPreamble)
-      ls.push(`          ${mapPreamble}`);
+    if (preambleLine)
+      ls.push(`          ${preambleLine}`);
     if (idxLine)
       ls.push(`          ${idxLine}`);
-    ls.push(`          ${handlerCall}`);
+    ls.push(`          ;${handlerCall}`);
     ls.push(`        }`);
   } else {
     ls.push(`        const ${param} = ${arrayExpr}[idx]`);
-    if (mapPreamble)
-      ls.push(`        ${mapPreamble}`);
+    ls.push(`        if (${param}) {`);
+    if (preambleLine)
+      ls.push(`          ${preambleLine}`);
     if (idxLine)
-      ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`);
-    else
-      ls.push(`        if (${param}) ${handlerCall}`);
+      ls.push(`          ${idxLine}`);
+    ls.push(`          ;${handlerCall}`);
+    ls.push(`        }`);
   }
   ls.push(`      }`);
 }
 function emitStaticIndexLookup(ls, ev, handlerCall, lookup, containerVar) {
-  const { arrayExpr, param, mapPreamble, offset, indexParam } = lookup;
+  const { arrayExpr, param, mapPreamble, mapPreambleDeclaredNames, offset, indexParam } = lookup;
+  const preambleLine = preambleLineForHandler(mapPreamble, mapPreambleDeclaredNames, ev.handler);
   const idxLine = indexBindingLine(ev.handler, indexParam, "__idx");
   ls.push(`      let __el = ${varSlotId(ev.childSlotId)}El`);
   ls.push(`      while (__el.parentElement && __el.parentElement !== ${containerVar}) __el = __el.parentElement`);
@@ -18923,12 +19669,13 @@ function emitStaticIndexLookup(ls, ev, handlerCall, lookup, containerVar) {
   const idxOffset = buildLoopChildIndexSubtraction(offset ?? undefined);
   ls.push(`        const __idx = Array.from(${containerVar}.children).indexOf(__el)${idxOffset}`);
   ls.push(`        const ${param} = ${arrayExpr}[__idx]`);
-  if (mapPreamble)
-    ls.push(`        ${mapPreamble}`);
+  ls.push(`        if (${param}) {`);
+  if (preambleLine)
+    ls.push(`          ${preambleLine}`);
   if (idxLine)
-    ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`);
-  else
-    ls.push(`        if (${param}) ${handlerCall}`);
+    ls.push(`          ${idxLine}`);
+  ls.push(`          ;${handlerCall}`);
+  ls.push(`        }`);
   ls.push(`      }`);
 }
 
@@ -18961,12 +19708,29 @@ function emitPlain(lines, plan) {
     eventDelegation,
     childRefs,
     bodyIsMultiRoot,
-    profileLoopId
+    profileLoopId,
+    preambleRegions
   } = plan;
   const loopBfId = profileLoopId ? `, ${JSON.stringify(profileLoopId)}` : "";
   const unwrapInline = paramUnwrap ? `${paramUnwrap} ` : "";
   lines.push(`      __disposers.push(createDisposableEffect(() => {`);
-  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0) {
+  if (plan.flatMapLeafItem) {
+    lines.push(`        if (${containerVar}) mapArray(() => ${arrayExpr}, ${containerVar}, ${keyFn}, (__bfD, ${indexParam}, __existing) => {`);
+    lines.push(`          let __el = __existing`);
+    lines.push(`          if (!__el) { const __tpl = document.createElement('template'); __tpl.innerHTML = __bfD().h; __el = __tpl.content.firstElementChild }`);
+    lines.push(`          let __last = __existing ? undefined : __bfD().h`);
+    lines.push(`          createEffect(() => {`);
+    lines.push(`            const __html = __bfD().h`);
+    lines.push(`            if (__last === undefined) { __last = __html; return }`);
+    lines.push(`            if (__html !== __last) { __last = __html; patchLeaf(__el, __html) }`);
+    lines.push(`          })`);
+    lines.push(`          return __el`);
+    lines.push(`        }, '${markerId}'${loopBfId})`);
+    lines.push(`      }))`);
+    stringifyEventDelegation(lines, eventDelegation);
+    return;
+  }
+  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0 && preambleRegions.length === 0) {
     const cloneExpr = emitTemplateCloneInline(template);
     if (mapPreambleWrapped) {
       lines.push(`        if (${containerVar}) mapArray(() => ${arrayExpr}, ${containerVar}, ${keyFn}, (${paramHead}, ${indexParam}, __existing) => { ${unwrapInline}if (__existing) return __existing; ${mapPreambleWrapped}; ${cloneExpr} }, '${markerId}'${loopBfId})`);
@@ -18991,6 +19755,7 @@ function emitPlain(lines, plan) {
       stringifyReactiveEffects(lines, reactiveEffects, { indent: "          ", elVar: "__el", bodyIsMultiRoot });
     }
     emitLoopChildRefs(lines, childRefs, { indent: "          ", elVar: "__el", bodyIsMultiRoot });
+    emitPreambleRegionEffects(lines, preambleRegions, mapPreambleWrapped, { indent: "          ", elVar: "__el" });
     lines.push(`          return __el`);
     lines.push(`        }, '${markerId}'${loopBfId})`);
   }
@@ -19130,6 +19895,7 @@ function buildComponentLoopPlan(elem, profileComponentName) {
   const hasChildConds = elem.bindings.conditionals.length > 0;
   return {
     kind: "component",
+    rowConstruction: "dom-ops",
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     arrayExpr: buildChainedArrayExpr(elem),
@@ -19175,8 +19941,32 @@ function buildPlainLoopPlan(elem, profileComponentName) {
   const wrap = (expr) => wrapLoopParamAsAccessor(expr, elem.param, elem.paramBindings);
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(elem.param, elem.paramBindings);
   const hasReactive2 = elem.bindings.reactiveAttrs.length > 0 || elem.bindings.reactiveTexts.length > 0 || elem.bindings.conditionals.length > 0;
+  if (elem.flatMapClient) {
+    return {
+      kind: "plain",
+      rowConstruction: "string-template",
+      containerVar: `_${varSlotId(elem.slotId)}`,
+      markerId: elem.markerId,
+      profileLoopId: profileComponentName ? `${profileComponentName}#binding:${elem.slotId}` : undefined,
+      arrayExpr: `(${buildChainedArrayExpr(elem)}).flatMap(${elem.flatMapClient.params} => ${elem.flatMapClient.body})`,
+      keyFn: elem.flatMapClient.keyed ? "(__bfD, __bfI) => String(__bfD.k ?? __bfI)" : "null",
+      paramHead: "__bfD",
+      paramUnwrap: "",
+      indexParam: "__idx",
+      mapPreambleWrapped: "",
+      template: "",
+      reactiveEffects: null,
+      childRefs: [],
+      bodyIsMultiRoot: false,
+      anchored: false,
+      anchorKeyExpr: "__idx",
+      flatMapLeafItem: true,
+      preambleRegions: []
+    };
+  }
   return {
     kind: "plain",
+    rowConstruction: "string-template",
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${elem.slotId}` : undefined,
@@ -19185,12 +19975,16 @@ function buildPlainLoopPlan(elem, profileComponentName) {
     paramHead,
     paramUnwrap,
     indexParam: elem.index || "__idx",
-    mapPreambleWrapped: elem.mapPreamble ? wrap(elem.mapPreamble) : "",
+    mapPreambleWrapped: elem.preamble ? renderPreamble(elem.preamble, {
+      transformJs: wrap,
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true)
+    }) : "",
     template: elem.template,
     skeletonTemplate: elem.skeletonTemplate,
     skeletonPaths: elem.skeletonPaths,
     reactiveEffects: hasReactive2 ? buildLoopReactiveEffectsPlan(elem, profileComponentName) : null,
     childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
+    preambleRegions: buildPreambleRegionPlans(elem.preambleRegions, elem.param, elem.paramBindings),
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,
     anchored: elem.bodyIsItemConditional ?? false,
     anchorKeyExpr: elem.key ? wrap(elem.key) : elem.index || "__idx"
@@ -19212,6 +20006,7 @@ function buildStaticLoopPlan(elem, unsafeLocalNames, profileComponentName) {
   const childIndexExpr = buildLoopChildIndexExpr(indexParam, elem.offset);
   return {
     kind: "static",
+    rowConstruction: "string-template",
     containerVar: `_${varSlotId(elem.slotId)}`,
     arrayExpr: elem.array,
     param: elem.param,
@@ -19233,7 +20028,9 @@ function buildStaticLoopMaterialize(elem, unsafeLocalNames) {
     return null;
   return {
     itemTemplate: elem.staticItemTemplate,
-    mapPreamble: elem.mapPreamble ?? "",
+    mapPreamble: elem.preamble ? renderPreamble(elem.preamble, {
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true)
+    }) : "",
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false
   };
 }
@@ -19262,6 +20059,7 @@ function emitLoopUpdates(lines, ctx, unsafeLocalNames) {
       unsafeLocalNames,
       profileComponentName: ctx.profile ? ctx.componentName : undefined
     });
+    internalInvariant(!(elem.preamble && elem.preamble.builderNames.length > 0 && plan.rowConstruction === "dom-ops"), `loop variant '${plan.kind}' declares dom-ops row construction but received a JSX-bearing preamble — add a Phase-1 refusal (or wire renderPreamble support) for this shape`);
     stringifyLoop(lines, plan);
     emitLoopEventDelegation(lines, elem, plan.kind, ctx.profile ? ctx.componentName : undefined);
   }
@@ -20192,19 +20990,19 @@ function isJsxLike(expr) {
 function collectArrowParamNames(arrow) {
   const names = new Set;
   for (const p of arrow.parameters)
-    collectBindingNames(p.name, names);
+    collectBindingNames2(p.name, names);
   return names;
 }
-function collectBindingNames(name, out) {
+function collectBindingNames2(name, out) {
   const push = Array.isArray(out) ? (n) => out.push(n) : (n) => out.add(n);
   if (ts16.isIdentifier(name)) {
     push(name.text);
   } else if (ts16.isObjectBindingPattern(name)) {
-    name.elements.forEach((el) => collectBindingNames(el.name, out));
+    name.elements.forEach((el) => collectBindingNames2(el.name, out));
   } else if (ts16.isArrayBindingPattern(name)) {
     name.elements.forEach((el) => {
       if (!ts16.isOmittedExpression(el))
-        collectBindingNames(el.name, out);
+        collectBindingNames2(el.name, out);
     });
   }
 }
@@ -20213,12 +21011,12 @@ function collectFreeIdentifiers(arrow) {
   const bound = [];
   for (const p of arrow.parameters) {
     const names = [];
-    collectBindingNames(p.name, names);
+    collectBindingNames2(p.name, names);
     bound.push(...names);
   }
   function pushBindings(name) {
     const names = [];
-    collectBindingNames(name, names);
+    collectBindingNames2(name, names);
     bound.push(...names);
     return names;
   }
@@ -20345,7 +21143,7 @@ function collectModuleScopeNames(sourceFile) {
       names.add(stmt.name.text);
     else if (ts16.isVariableStatement(stmt)) {
       for (const decl of stmt.declarationList.declarations)
-        collectBindingNames(decl.name, names);
+        collectBindingNames2(decl.name, names);
     } else if (ts16.isImportDeclaration(stmt) && stmt.importClause) {
       const ic = stmt.importClause;
       if (ic.name)
@@ -21364,8 +22162,13 @@ function walkNode(node, meta, bindings, matchers, errors, seen) {
         for (const child of nested.children)
           walkNode(child, meta, loopBindings, matchers, errors, seen);
       }
-      for (const frag of node.flatMapCallback?.fragments ?? []) {
-        walkNode(frag.ir, meta, loopBindings, matchers, errors, seen);
+      for (const seg of node.flatMapCallback?.segments ?? []) {
+        if (seg.kind === "jsx")
+          walkNode(seg.ir, meta, loopBindings, matchers, errors, seen);
+      }
+      for (const seg of node.preamble?.segments ?? []) {
+        if (seg.kind === "jsx")
+          walkNode(seg.ir, meta, loopBindings, matchers, errors, seen);
       }
       break;
     }
@@ -21427,7 +22230,7 @@ function compileMultipleComponents(source, filePath, componentNames, options) {
   const entries = [];
   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);
       continue;
@@ -21736,7 +22539,7 @@ function compileJSX(source, filePath, options) {
   if (componentNames.length > 1) {
     return compileMultipleComponents(compileSource, filePath, componentNames, options);
   }
-  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);
     const exportedModuleSignals = ctx.signals.filter((s2) => s2.isModule && s2.isExported);
@@ -21936,6 +22739,7 @@ class BaseAdapter {
 import { BF_SCOPE as BF_SCOPE4, BF_SLOT, BF_COND } from "@barefootjs/shared";
 class JsxAdapter extends BaseAdapter {
   componentName = "";
+  acceptsCallbackBody = () => true;
   formatImportSpecifiers(specifiers) {
     const defaultSpec = specifiers.find((s) => s.isDefault);
     const namespaceSpec = specifiers.find((s) => s.isNamespace);
@@ -22281,6 +23085,10 @@ export default ${this.componentName}` : "";
     const indexParam = loop.index ? `, ${loop.index}` : "";
     const children = this.renderChildren(loop.children);
     const safeChildren = children.startsWith("{") ? `<>${children}</>` : children;
+    const preamble = loop.preamble?.ssrText;
+    if (preamble) {
+      return `{${loop.array}.map((${loop.param}${indexParam}) => { ${preamble} return ${safeChildren} })}`;
+    }
     return `{${loop.array}.map((${loop.param}${indexParam}) => ${safeChildren})}`;
   }
   renderComponent(comp) {
@@ -22481,8 +23289,13 @@ function collectLoopBoundNames(ir) {
           for (const child of nested.children)
             visit3(child);
         }
-        for (const frag of node.flatMapCallback?.fragments ?? []) {
-          visit3(frag.ir);
+        for (const seg of node.flatMapCallback?.segments ?? []) {
+          if (seg.kind === "jsx")
+            visit3(seg.ir);
+        }
+        for (const seg of node.preamble?.segments ?? []) {
+          if (seg.kind === "jsx")
+            visit3(seg.ir);
         }
         break;
       case "conditional":
@@ -23058,12 +23871,16 @@ function restNamesMisused(loop, names) {
     check(l.array);
     check(l.templateArray);
     check(l.key);
-    check(l.mapPreamble);
-    check(l.templateMapPreamble);
+    if (l.preamble) {
+      check(preambleAnalysisText(l.preamble));
+      check(preambleAnalysisTemplateText(l.preamble));
+    }
     if (l.flatMapCallback) {
-      check(l.flatMapCallback.body);
-      check(l.flatMapCallback.templateBody);
-      l.flatMapCallback.fragments.forEach((f) => visit3(f.ir));
+      check(preambleAnalysisText(l.flatMapCallback));
+      for (const seg of l.flatMapCallback.segments) {
+        if (seg.kind === "jsx")
+          visit3(seg.ir);
+      }
     }
     l.children.forEach(visit3);
   };