@barefootjs/jsx 0.26.3 → 0.26.4

package/dist/index.js

@@ -3252,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)} + '"' : ''}`;
 }
@@ -3387,12 +3387,57 @@ 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, 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":
@@ -3527,7 +3572,7 @@ function irToHtmlTemplate(node, restSpreadNames, loopDepth = 0, loopParams, bran
       let mapExpr;
       if (node.flatMapCallback) {
         const body = 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} => ${body}).join('')}`;
       } else if (node.preamble) {
@@ -3817,7 +3862,7 @@ function irToPlaceholderTemplate(node, restSpreadNames, loopDepth = 0, loopParam
       let mapExpr;
       if (node.flatMapCallback) {
         const body = renderPreamble(node.flatMapCallback, {
-          renderLeaf: (ir) => irToPlaceholderTemplate(ir, restSpreadNames, loopDepth + 1, loopParams)
+          renderLeaf: (ir) => irToPlaceholderTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams)
         });
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`;
       } else if (node.preamble) {
@@ -4443,7 +4488,7 @@ function generateCsrTemplateWithOpts(node, opts) {
         const body = renderPreamble(node.flatMapCallback, {
           textVariant: "template",
           transformJs: (t) => applyPropsRewrite(t, propsObjectName ?? null),
-          renderLeaf: (ir) => recurseInLoopBody(ir)
+          renderLeaf: (ir) => recurseInLoopBody(stripLeafKeyAttr(ir))
         });
         mapExpr = `\${${iterArrayExpr}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`;
       } else if (node.preamble) {
@@ -11710,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)
@@ -11755,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;
@@ -12041,12 +12168,34 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
           }
         }
       }
-      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);
@@ -12058,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) {
@@ -12110,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",
@@ -12140,6 +12300,7 @@ function transformMapCall(node, ctx, isClientOnly = false, method = "map") {
     depth,
     clientOnly: isClientOnly || undefined,
     preamble,
+    preambleRegions: preambleRegions && preambleRegions.length > 0 ? preambleRegions : undefined,
     paramType,
     indexType,
     paramBindings,
@@ -12202,6 +12363,28 @@ function buildFlatMapCallback(callback, body, ctx) {
     }));
     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;
+    }
+  }
   const pieces = reconstructAsSegments(body, ctx.sourceFile, ctx.analyzer.typeExcludeRanges, leafSpans);
   const segments = pieces.map((piece) => {
     if ("marker" in piece)
@@ -12216,6 +12399,25 @@ function buildFlatMapCallback(callback, body, ctx) {
     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":
@@ -12258,6 +12460,40 @@ function flagArrayChildExpressions(nodes, declared) {
     }
   }
 }
+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);
@@ -13635,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;
@@ -14190,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) {
@@ -14204,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;
@@ -14214,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) {
@@ -14266,7 +14507,17 @@ function collectElements(node, ctx, siblingOffsets, insideConditional = false) {
           raw: l.sortComparator.raw
         } : undefined,
         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(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 }) => {
@@ -14423,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,
@@ -14448,6 +14702,7 @@ function collectBranchLoops(node, ctx, siblingOffsets) {
         template: childTemplate,
         containerSlotId: containerSlot,
         preamble: n.preamble,
+        preambleRegions: n.preambleRegions,
         nestedComponents: useElementReconciliation ? n.nestedComponents : undefined,
         bindings: branchBindings,
         innerLoops: useElementReconciliation ? innerLoopsCollected : undefined,
@@ -14461,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
       });
     }
   });
@@ -14836,6 +15100,13 @@ function buildReferencesGraph(ctx, irRoot) {
         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);
@@ -15013,6 +15284,8 @@ var RUNTIME_IMPORT_CANDIDATES = [
   "getLoopNodes",
   "mapArray",
   "mapArrayAnchored",
+  "patchLeaf",
+  "patchSlotRange",
   "createDisposableEffect",
   "createComponent",
   "renderChild",
@@ -17015,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) => {
@@ -18029,8 +18311,9 @@ function buildDynamicLoopDelegationPlan(elem, profileComponentName) {
       key: elem.key,
       index: elem.index,
       mapPreamble: elem.preamble ? renderPreamble(elem.preamble, {
-        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true)
-      }) : null
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
+      }) : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? []
     })
   };
 }
@@ -18047,8 +18330,9 @@ function buildBranchLoopDelegationPlan(loop, cv, profileComponentName) {
       key: loop.key,
       index: loop.index,
       mapPreamble: loop.preamble ? renderPreamble(loop.preamble, {
-        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true)
-      }) : null
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
+      }) : null,
+      mapPreambleDeclaredNames: loop.preamble?.declaredNames ?? []
     })
   };
 }
@@ -18063,8 +18347,9 @@ function buildStaticArrayDelegationPlan(elem, profileComponentName) {
       arrayExpr: buildChainedArrayExpr(elem),
       param: elem.param,
       mapPreamble: elem.preamble ? renderPreamble(elem.preamble, {
-        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true)
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true)
       }) : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? [],
       offset: elem.offset ?? null,
       indexParam: elem.index ?? null
     }
@@ -18081,6 +18366,7 @@ function buildKeyedOrIndexLookup(args) {
       paramBindings: args.paramBindings,
       keyWithItem,
       mapPreamble: args.mapPreamble,
+      mapPreambleDeclaredNames: args.mapPreambleDeclaredNames,
       hasBindings,
       indexParam: args.index
     };
@@ -18090,6 +18376,7 @@ function buildKeyedOrIndexLookup(args) {
     arrayExpr: args.array,
     param: args.param,
     mapPreamble: args.mapPreamble,
+    mapPreambleDeclaredNames: args.mapPreambleDeclaredNames,
     hasBindings,
     indexParam: args.index
   };
@@ -18111,14 +18398,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 : 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",
@@ -18137,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
   };
@@ -18784,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":
@@ -18825,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;
@@ -18837,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);
@@ -18885,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})`);
 }
@@ -19195,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;
@@ -19240,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}]')`);
@@ -19250,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;
@@ -19290,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) {`);
@@ -19308,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`);
@@ -19334,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(`      }`);
 }
 
@@ -19372,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})`);
@@ -19402,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})`);
   }
@@ -19587,6 +19941,29 @@ 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",
@@ -19607,6 +19984,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,
     anchorKeyExpr: elem.key ? wrap(elem.key) : elem.index || "__idx"