@barefootjs/cli 0.26.3 → 0.26.4

package/dist/docs/core/rendering/jsx-compatibility.md

@@ -52,6 +52,21 @@ return <div>...</div>
 ))}
 ```
 
+`.flatMap()` expands nested collections into a flat run of keyed elements. A pure projection body — the nested `.map()` as the whole body, expression or single-`return` block — compiles on every adapter; a body with statements before the projection (early returns, `const`s) runs as JS on JS-runtime adapters and needs [`/* @client */`](./client-directive.md) on DSL backends:
+
+```tsx
+// ✅ Projection — works on every adapter
+{todos().flatMap(todo => todo.tags.map(tag => (
+  <li key={`${todo.id}:${tag}`}>{tag}</li>
+)))}
+
+// ✅ Statement body — JS-runtime adapters; /* @client */ on Go/Mojo etc.
+{todos().flatMap(todo => {
+  if (todo.hidden) return []
+  return todo.tags.map(tag => <li key={`${todo.id}:${tag}`}>{tag}</li>)
+})}
+```
+
 `.sort()` and `.toSorted()` can be chained with `.map()` and `.filter()`:
 
 ```tsx
@@ -105,7 +120,9 @@ Some JavaScript expressions cannot be translated into marked template syntax. Wh
 |---|---|---|
 | `.filter()` with destructured param (`({done}) => done`) | works (runs as JS) | **BF101** |
 | `.filter()` with `function` keyword callback | works | **BF101** |
-| `.reduce()`, `.forEach()`, `.flatMap()` | works | **BF101** |
+| `.reduce()`, `.forEach()`, value-returning `.flatMap()` with an off-catalogue projection | works | **BF101** |
+| JSX-returning `.flatMap()` projection (`items.flatMap(it => it.tags.map(tag => <li key={...}/>))`) | works | works |
+| JSX-returning `.flatMap()` with a statement body (early `return`, `const` before the projection) | works (runs as JS) | **BF021** |
 | Nested `.filter()` / `.map()` in a filter predicate (`x => x.tags.filter(...).length > 0`) | works | works |
 | Nested `.some()` / `.find()` / `.reduce()` in a filter predicate | works | **BF101** |
 | Sort comparator that's a multi-statement block body or `localeCompare(b, locale, opts)` | works (runs as JS) | **BF021** |

package/dist/index.js

@@ -3695,7 +3695,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)} + '"' : ''}`;
 }
@@ -3815,12 +3815,54 @@ function renderPreamble(preamble, opts) {
     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, void 0, void 0, 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, void 0, void 0, true)).join("");
+  return `${chained}.map(${params} => ({ k: ${key}, h: \`${html}\` }))`;
+}
 function escapeLeafTextExpressions(ir) {
   switch (ir.type) {
     case "element":
@@ -3949,7 +3991,7 @@ function irToHtmlTemplate(node, restSpreadNames, loopDepth = 0, loopParams, bran
       let mapExpr;
       if (node.flatMapCallback) {
         const body2 = renderPreamble(node.flatMapCallback, {
-          renderLeaf: (ir) => irToHtmlTemplate(ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop)
+          renderLeaf: (ir) => irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop)
         });
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body2}).join('')}`;
       } else if (node.preamble) {
@@ -4200,7 +4242,8 @@ function irToPlaceholderTemplate(node, restSpreadNames, loopDepth = 0, loopParam
       let mapExpr;
       if (node.flatMapCallback) {
         const body2 = renderPreamble(node.flatMapCallback, {
-          renderLeaf: (ir) => irToPlaceholderTemplate(ir, restSpreadNames, loopDepth + 1, loopParams)
+          // Leaf `key` stripped — see the irToHtmlTemplate site above.
+          renderLeaf: (ir) => irToPlaceholderTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams)
         });
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body2}).join('')}`;
       } else if (node.preamble) {
@@ -4799,7 +4842,8 @@ function generateCsrTemplateWithOpts(node, opts) {
         const body2 = renderPreamble(node.flatMapCallback, {
           textVariant: "template",
           transformJs: (t) => applyPropsRewrite(t, propsObjectName ?? null),
-          renderLeaf: (ir) => recurseInLoopBody(ir)
+          // Leaf `key` stripped — see the irToHtmlTemplate site above.
+          renderLeaf: (ir) => recurseInLoopBody(stripLeafKeyAttr(ir))
         });
         mapExpr = `\${${iterArrayExpr}.flatMap(${node.flatMapCallback.params} => ${body2}).join('')}`;
       } else if (node.preamble) {
@@ -11596,6 +11640,76 @@ function checkLoopKey(callback, ctx2, isNested) {
     return;
   }
 }
+function flatMapProjectionCall(body2) {
+  let expr;
+  if (ts11.isBlock(body2)) {
+    const real = body2.statements;
+    if (real.length !== 1 || !ts11.isReturnStatement(real[0]) || !real[0].expression) return null;
+    expr = real[0].expression;
+  } else {
+    expr = body2;
+  }
+  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 visit3 = (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 name2 = attr.name.getText();
+          if (/^on[A-Z]/.test(name2)) {
+            ok = false;
+            return;
+          }
+        }
+      }
+    }
+    if (ts11.isCallExpression(n) && getMapLikeMethod(n) && containsJsxInExpression(n)) {
+      ok = false;
+      return;
+    }
+    ts11.forEachChild(n, visit3);
+  };
+  visit3(el);
+  return ok;
+}
 function loopBodyIsMultiRoot(children2) {
   const real = children2.filter(
     (c) => !(c.type === "text" && typeof c.value === "string" && !c.value.trim())
@@ -11641,6 +11755,7 @@ function extractItemConditionalKey(cond) {
 }
 function transformMapCall(node, ctx2, isClientOnly = false, method2 = "map") {
   const isNested = ctx2.loopParams.size > 0;
+  const diagCountAtEntry = ctx2.analyzer.errors.length;
   const depth = ctx2.loopDepth;
   const propAccess = node.expression;
   const mapSource = propAccess.expression;
@@ -11978,12 +12093,39 @@ function transformMapCall(node, ctx2, isClientOnly = false, method2 = "map") {
           }
         }
       }
-      if (method2 === "flatMap" && children2.length === 0) {
+      if (method2 === "flatMap" && children2.length === 0 && !flatMapProjectionCall(body2)) {
         flatMapCallback = buildFlatMapCallback(callback, body2, ctx2);
       }
     } else {
       tryTransformRenderableBody(body2);
     }
+    if (method2 === "flatMap" && children2.length === 0 && !flatMapCallback) {
+      const projection = flatMapProjectionCall(body2);
+      if (projection) {
+        const transformed = transformJsxExpression(projection, ctx2, isClientOnly);
+        if (transformed && transformed.type === "loop") {
+          children2 = [transformed];
+        }
+      }
+    }
+    if (method2 === "flatMap" && children2.length === 0 && !flatMapCallback && !ts11.isBlock(body2)) {
+      flatMapCallback = buildFlatMapCallback(callback, body2, ctx2);
+    }
+    if (flatMapCallback) preamble = void 0;
+    if (flatMapCallback && !isClientOnly && !(ctx2.analyzer.acceptsCallbackBody?.("flatMap") ?? false)) {
+      ctx2.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          getSourceLocation(body2, ctx2.sourceFile, ctx2.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) ctx2.loopParams.delete(b.name);
     } else {
@@ -11993,6 +12135,22 @@ function transformMapCall(node, ctx2, isClientOnly = false, method2 = "map") {
     ctx2.loopDepth--;
   }
   if (children2.length === 0 && !flatMapCallback) {
+    const cb = node.arguments[0];
+    const cbBody = cb && (ts11.isArrowFunction(cb) || ts11.isFunctionExpression(cb)) ? cb.body : void 0;
+    if (cbBody && containsJsxInExpression(cbBody) && ctx2.analyzer.errors.length === diagCountAtEntry) {
+      ctx2.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          getSourceLocation(cbBody, ctx2.sourceFile, ctx2.filePath),
+          {
+            message: `A .${method2}() callback that builds JSX in this shape cannot be compiled \u2014 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]) && children2.length > 0) {
@@ -12049,6 +12207,7 @@ function transformMapCall(node, ctx2, isClientOnly = false, method2 = "map") {
   const hasCalls = exprHasFunctionCalls(arrayExpr);
   const isDirectPropArray = method2 !== "flatMap" && isArrayExprDirectPropRef(arrayExpr, ctx2);
   const isStaticArray = !isSignalOrMemoArray(array, ctx2) && !isDirectPropArray && !hasCalls && !objectIteration;
+  const preambleRegions = preamble && !isStaticArray ? collectPreambleRegions(children2, new Set(preamble.declaredNames), ctx2) : void 0;
   const nestedComponents = collectNestedComponents(children2).filter((c) => c.name !== childComponent?.name);
   return {
     type: "loop",
@@ -12086,6 +12245,7 @@ function transformMapCall(node, ctx2, isClientOnly = false, method2 = "map") {
     depth,
     clientOnly: isClientOnly || void 0,
     preamble,
+    preambleRegions: preambleRegions && preambleRegions.length > 0 ? preambleRegions : void 0,
     paramType,
     indexType,
     paramBindings,
@@ -12146,6 +12306,40 @@ function buildFlatMapCallback(callback, body2, ctx2) {
     );
     return void 0;
   }
+  for (const leafIr of leafIrs) {
+    if (leafIr.type !== "element") {
+      const loc = "loc" in leafIr && leafIr.loc ? leafIr.loc : getSourceLocation(body2, ctx2.sourceFile, ctx2.filePath);
+      ctx2.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          loc,
+          {
+            message: "A JSX leaf produced by a .flatMap() callback must be a single element \u2014 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 void 0;
+    }
+    if (flatMapLeafNeedsWiring(leafIr)) {
+      const loc = "loc" in leafIr && leafIr.loc ? leafIr.loc : getSourceLocation(body2, ctx2.sourceFile, ctx2.filePath);
+      ctx2.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 \u2014 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 \u2014 the descriptor path has no per-element wiring on any backend, so /* @client */ does not lift this."
+            }
+          }
+        )
+      );
+      return void 0;
+    }
+  }
   const pieces = reconstructAsSegments(body2, ctx2.sourceFile, ctx2.analyzer.typeExcludeRanges, leafSpans);
   const segments = pieces.map((piece) => {
     if ("marker" in piece) return { kind: "jsx", ir: leafIrs[piece.marker] };
@@ -12159,6 +12353,23 @@ function buildFlatMapCallback(callback, body2, ctx2) {
     rawBody: tsxSourceText(body2.getText(ctx2.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":
@@ -12202,6 +12413,39 @@ function flagArrayChildExpressions(nodes, declared) {
     }
   }
 }
+function collectPreambleRegions(nodes, declared, ctx2) {
+  const regions = [];
+  const visit3 = (list) => {
+    for (const node of list) {
+      switch (node.type) {
+        case "expression": {
+          const refs = extractFreeIdentifiersFromText(node.expr);
+          const usesPreambleLocal = [...refs].some((r2) => declared.has(r2));
+          if (usesPreambleLocal) {
+            if (!node.slotId) node.slotId = generateSlotId(ctx2);
+            node.preambleRegion = true;
+            node.reactive = true;
+            regions.push({
+              slotId: node.slotId,
+              expr: node.expr,
+              joinArrayChild: node.joinArrayChild || void 0
+            });
+          }
+          break;
+        }
+        case "element":
+        case "fragment":
+          visit3(node.children);
+          break;
+        case "conditional":
+          visit3([node.whenTrue, ...node.whenFalse ? [node.whenFalse] : []]);
+          break;
+      }
+    }
+  };
+  visit3(nodes);
+  return regions;
+}
 function collectBindingNames(name2, out) {
   if (ts11.isIdentifier(name2)) {
     out.add(name2.text);
@@ -13570,6 +13814,7 @@ function collectLoopChildReactiveTexts(node, ctx2, loopParam, loopParamBindings,
     ...stopAt("loop", "async", "ifStatement"),
     expression: ({ node: n, scope: insideConditional }) => {
       if (!n.slotId) return;
+      if (n.preambleRegion) return;
       const originFreeIds = freeIdsFromRefs(n.origin?.freeRefs);
       const expanded = expandConstantForReactivity(n.expr, ctx2, originFreeIds);
       const reactive = classifyReactivity(expanded.expr, ctx2, loopParam, loopParamBindings, expanded.freeIds).kind !== "none" || decideWrapFromAstFlags(n).wrap;
@@ -14102,10 +14347,13 @@ function collectElements(node, ctx2, 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] : void 0;
       const childHandlers = [];
-      const bindings = collectLoopChildBindings(l.children, ctx2, siblingOffsets, l.param, l.paramBindings);
-      for (const child of l.children) {
-        childHandlers.push(...collectEventHandlersFromIR(child));
+      const bindings = projectionInner ? emptyLoopChildBindings() : collectLoopChildBindings(l.children, ctx2, 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) {
@@ -14115,7 +14363,7 @@ function collectElements(node, ctx2, siblingOffsets, insideConditional = false)
           }
         }
       }
-      const { useElementReconciliation, innerLoops } = decideLoopRendering(l, siblingOffsets, ctx2);
+      const { useElementReconciliation, innerLoops } = projectionInner ? { useElementReconciliation: false, innerLoops: void 0 } : decideLoopRendering(l, siblingOffsets, ctx2);
       let template = "";
       let staticItemTemplate;
       let skeletonTemplate;
@@ -14133,7 +14381,7 @@ function collectElements(node, ctx2, siblingOffsets, insideConditional = false)
             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(ctx2), 0, loopParamSpec) : irToHtmlTemplate(l.children[0], buildRestSpreadNames(ctx2), 0, loopParamSpec);
         if (l.isStaticArray) {
@@ -14185,7 +14433,17 @@ function collectElements(node, ctx2, siblingOffsets, insideConditional = false)
           raw: l.sortComparator.raw
         } : void 0,
         chainOrder: l.chainOrder,
-        preamble: l.preamble
+        preamble: l.preamble,
+        preambleRegions: l.preambleRegions,
+        flatMapClient: projectionInner ? {
+          params: l.index ? `(${l.param}, ${l.index})` : `(${l.param})`,
+          body: renderFlatMapProjectionClientBody(projectionInner, buildRestSpreadNames(ctx2)),
+          keyed: projectionInner.key !== null
+        } : l.flatMapCallback ? {
+          params: l.flatMapCallback.params,
+          body: renderFlatMapClientBody(l.flatMapCallback, buildRestSpreadNames(ctx2)),
+          keyed: flatMapCallbackHasKeyedLeaf(l.flatMapCallback)
+        } : void 0
       });
     },
     component: ({ node: c, descend, descendJsxChildren }) => {
@@ -14340,15 +14598,18 @@ function collectBranchLoops(node, ctx2, siblingOffsets) {
     loop: ({ node: n, scope: parentSlotId }) => {
       const containerSlot = parentSlotId ?? n.slotId;
       if (!containerSlot) return;
-      const { useElementReconciliation, innerLoops: innerLoopsCollected } = decideLoopRendering(n, siblingOffsets, void 0);
+      const projectionInner = n.method === "flatMap" && n.children.length === 1 && n.children[0].type === "loop" ? n.children[0] : void 0;
+      const { useElementReconciliation, innerLoops: innerLoopsCollected } = projectionInner ? { useElementReconciliation: false, innerLoops: void 0 } : decideLoopRendering(n, siblingOffsets, void 0);
       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, void 0, 0, branchLoopParamSpec)).join("");
       }
-      const branchBindings = ctx2 ? collectLoopChildBindings(n.children, ctx2, siblingOffsets, n.param, n.paramBindings) : emptyLoopChildBindings();
+      const branchBindings = ctx2 && !projectionInner ? collectLoopChildBindings(n.children, ctx2, siblingOffsets, n.param, n.paramBindings) : emptyLoopChildBindings();
       loops.push({
         kind: "branch",
         array: n.array,
@@ -14365,6 +14626,7 @@ function collectBranchLoops(node, ctx2, siblingOffsets) {
         template: childTemplate,
         containerSlotId: containerSlot,
         preamble: n.preamble,
+        preambleRegions: n.preambleRegions,
         nestedComponents: useElementReconciliation ? n.nestedComponents : void 0,
         bindings: branchBindings,
         innerLoops: useElementReconciliation ? innerLoopsCollected : void 0,
@@ -14378,7 +14640,16 @@ function collectBranchLoops(node, ctx2, siblingOffsets) {
           paramB: n.sortComparator.paramB,
           raw: n.sortComparator.raw
         } : void 0,
-        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)
+        } : void 0
       });
     }
   });
@@ -14774,6 +15045,12 @@ function buildReferencesGraph(ctx2, irRoot) {
       if (l.filterPredicate) addExprEdges(ROOT_SOURCE, l.filterPredicate.raw, "template-closure");
       if (l.sortComparator) addExprEdges(ROOT_SOURCE, l.sortComparator.raw, "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);
       if (l.nestedComponents) {
@@ -15055,6 +15332,8 @@ var init_imports = __esm({
       "getLoopNodes",
       "mapArray",
       "mapArrayAnchored",
+      "patchLeaf",
+      "patchSlotRange",
       "createDisposableEffect",
       "createComponent",
       "renderChild",
@@ -17006,6 +17285,14 @@ function destructureLoopParam(param, paramBindings) {
   }
   return { head: param, unwrap: "" };
 }
+function buildPreambleRegionPlans(regions, loopParam, loopParamBindings) {
+  if (!regions || regions.length === 0) return [];
+  return regions.map((r2) => {
+    const wrapped = wrapLoopParamAsAccessor(r2.expr, loopParam, loopParamBindings);
+    const valueExpr = r2.joinArrayChild ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')` : `escapeText(${wrapped})`;
+    return { slotId: r2.slotId, valueExpr };
+  });
+}
 function buildComponentPropsExpr2(comp, loopParam, loopParamBindings) {
   const wrap = loopParam ? (expr) => wrapLoopParamAsAccessor(expr, loopParam, loopParamBindings) : (expr) => expr;
   const entries2 = comp.props.map((p) => {
@@ -18104,9 +18391,16 @@ function buildDynamicLoopDelegationPlan(elem, profileComponentName) {
       paramBindings: elem.paramBindings,
       key: elem.key,
       index: elem.index,
+      // No loopParams spec here (unlike the row-render context) — in the
+      // delegated handler `elem.param` is bound to the plain `.find()`/
+      // indexed result, not a signal accessor, so leaf refs must stay in
+      // their literal (`t.name`) form. Passing a loopParams spec here was
+      // BUG-3: it rewrote leaf refs to accessor-call form (`t().name`),
+      // which throws since `t` is a plain object in this scope.
       mapPreamble: elem.preamble ? renderPreamble(elem.preamble, {
-        renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, [{ param: elem.param, bindings: elem.paramBindings }], void 0, true)
-      }) : null
+        renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, void 0, void 0, true)
+      }) : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? []
     })
   };
 }
@@ -18123,9 +18417,12 @@ function buildBranchLoopDelegationPlan(loop, cv, profileComponentName) {
       paramBindings: loop.paramBindings,
       key: loop.key,
       index: loop.index,
+      // See note in `buildDynamicLoopDelegationPlan` above (BUG-3): no
+      // loopParams spec — leaf refs must stay in plain-object form here.
       mapPreamble: loop.preamble ? renderPreamble(loop.preamble, {
-        renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, [{ param: loop.param, bindings: loop.paramBindings }], void 0, true)
-      }) : null
+        renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, void 0, void 0, true)
+      }) : null,
+      mapPreambleDeclaredNames: loop.preamble?.declaredNames ?? []
     })
   };
 }
@@ -18142,9 +18439,12 @@ function buildStaticArrayDelegationPlan(elem, profileComponentName) {
       // array too (#1434).
       arrayExpr: buildChainedArrayExpr(elem),
       param: elem.param,
+      // See note in `buildDynamicLoopDelegationPlan` above (BUG-3): no
+      // loopParams spec — leaf refs must stay in plain-object form here.
       mapPreamble: elem.preamble ? renderPreamble(elem.preamble, {
-        renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, [{ param: elem.param, bindings: elem.paramBindings }], void 0, true)
+        renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, void 0, void 0, true)
       }) : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? [],
       offset: elem.offset ?? null,
       indexParam: elem.index ?? null
     }
@@ -18161,6 +18461,7 @@ function buildKeyedOrIndexLookup(args2) {
       paramBindings: args2.paramBindings,
       keyWithItem,
       mapPreamble: args2.mapPreamble,
+      mapPreambleDeclaredNames: args2.mapPreambleDeclaredNames,
       hasBindings,
       indexParam: args2.index
     };
@@ -18170,6 +18471,7 @@ function buildKeyedOrIndexLookup(args2) {
     arrayExpr: args2.array,
     param: args2.param,
     mapPreamble: args2.mapPreamble,
+    mapPreambleDeclaredNames: args2.mapPreambleDeclaredNames,
     hasBindings,
     indexParam: args2.index
   };
@@ -18198,14 +18500,16 @@ 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 : void 0,
+    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",
@@ -18226,6 +18530,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}` : void 0
   };
@@ -18937,6 +19242,20 @@ 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":
@@ -18978,8 +19297,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;
@@ -18990,7 +19325,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);
@@ -19038,6 +19373,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})`);
 }
@@ -19370,6 +19706,11 @@ function indexBindingLine(handler, indexParam, indexExpr) {
   if (!extractFreeIdentifiersFromText(handler).has(indexParam)) 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((name2) => free.has(name2)) ? mapPreamble : null;
+}
 function stringifyEventDelegation(lines, plan) {
   const { containerVar, events, itemLookup, profileComponentName } = plan;
   const eventsByName = /* @__PURE__ */ new Map();
@@ -19414,7 +19755,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('[${BF_KEY}]')`);
@@ -19424,15 +19766,17 @@ 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}`);
-      if (idxLine2) ls.push(`        if (${param}) { ${idxLine2}; ${handlerCall} }`);
-      else ls.push(`        if (${param}) ${handlerCall}`);
+      ls.push(`        if (${param}) {`);
+      if (preambleLine) ls.push(`          ${preambleLine}`);
+      if (idxLine2) ls.push(`          ${idxLine2}`);
+      ls.push(`          ;${handlerCall}`);
+      ls.push(`        }`);
     }
     ls.push(`      }`);
     return;
@@ -19459,13 +19803,16 @@ 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)`);
-  if (idxLine) ls.push(`      if (${allParams.join(" && ")}) { ${idxLine}; ${handlerCall} }`);
-  else ls.push(`      if (${allParams.join(" && ")}) ${handlerCall}`);
+  ls.push(`      if (${allParams.join(" && ")}) {`);
+  if (preambleLine) ls.push(`        ${preambleLine}`);
+  if (idxLine) 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) {`);
@@ -19474,20 +19821,23 @@ 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}`);
-    if (idxLine) ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`);
-    else ls.push(`        if (${param}) ${handlerCall}`);
+    ls.push(`        if (${param}) {`);
+    if (preambleLine) ls.push(`          ${preambleLine}`);
+    if (idxLine) ls.push(`          ${idxLine}`);
+    ls.push(`          ;${handlerCall}`);
+    ls.push(`        }`);
   }
   ls.push(`      }`);
 }
 function emitStaticIndexLookup(ls, ev, handlerCall, lookup, containerVar) {
-  const { arrayExpr, param, mapPreamble, offset: offset2, indexParam } = lookup;
+  const { arrayExpr, param, mapPreamble, mapPreambleDeclaredNames, offset: offset2, 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`);
@@ -19495,9 +19845,11 @@ function emitStaticIndexLookup(ls, ev, handlerCall, lookup, containerVar) {
   const idxOffset = buildLoopChildIndexSubtraction(offset2 ?? void 0);
   ls.push(`        const __idx = Array.from(${containerVar}.children).indexOf(__el)${idxOffset}`);
   ls.push(`        const ${param} = ${arrayExpr}[__idx]`);
-  if (mapPreamble) ls.push(`        ${mapPreamble}`);
-  if (idxLine) ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`);
-  else ls.push(`        if (${param}) ${handlerCall}`);
+  ls.push(`        if (${param}) {`);
+  if (preambleLine) ls.push(`          ${preambleLine}`);
+  if (idxLine) ls.push(`          ${idxLine}`);
+  ls.push(`          ;${handlerCall}`);
+  ls.push(`        }`);
   ls.push(`      }`);
 }
 var NON_BUBBLING_EVENTS;
@@ -19548,12 +19900,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})`);
@@ -19578,6 +19947,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})`);
   }
@@ -19795,6 +20165,31 @@ 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}` : void 0,
+      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,
+      // flatMap loops carry no `MapCallbackPreamble` (jsx-to-ir.ts drops it
+      // for flatMapCallback), so there is nothing to patch here.
+      preambleRegions: []
+    };
+  }
   return {
     kind: "plain",
     rowConstruction: "string-template",
@@ -19818,6 +20213,7 @@ function buildPlainLoopPlan(elem, profileComponentName) {
     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,
     // Fall back to the iteration index when the loop has no key. A whole-item

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/cli",
-  "version": "0.26.3",
+  "version": "0.26.4",
   "description": "CLI for agent-driven UI component discovery and scaffolding",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,11 +29,11 @@
   "dependencies": {
     "esbuild": "^0.25.0",
     "typescript": "^5.0.0",
-    "@barefootjs/client": "0.26.3",
-    "@barefootjs/shared": "0.26.3"
+    "@barefootjs/client": "0.26.4",
+    "@barefootjs/shared": "0.26.4"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.26.3",
+    "@barefootjs/jsx": "0.26.4",
     "@types/node": "^22.0.0",
     "@happy-dom/global-registrator": "^20.0.11",
     "happy-dom": "^20.0.11"