@barefootjs/jsx 0.26.3 → 0.26.4

package/src/ir-to-client-js/control-flow/stringify/event-delegation.ts

@@ -74,6 +74,26 @@ function indexBindingLine(handler: string, indexParam: string | null, indexExpr:
   return `const ${indexParam} = ${indexExpr}`
 }
 
+/**
+ * Splice-only-when-referenced (#3, BUG-3 fix part 2): a preamble is dead
+ * weight for an event whose handler never reads one of the names it
+ * declares — the common case (an unused array builder like `cells` in the
+ * BUG-3 repro). Only emit `mapPreamble` when `handler`'s free identifiers
+ * intersect `declaredNames`; otherwise the delegated handler pays nothing
+ * for a preamble it never uses. `declaredNames` is empty whenever
+ * `mapPreamble` is `null`, so the `!mapPreamble` short-circuit is mostly
+ * redundant but keeps this correct-by-construction if that ever changes.
+ */
+function preambleLineForHandler(
+  mapPreamble: string | null,
+  declaredNames: readonly string[],
+  handler: string,
+): string | null {
+  if (!mapPreamble || declaredNames.length === 0) return null
+  const free = extractFreeIdentifiersFromText(handler)
+  return declaredNames.some((name) => free.has(name)) ? mapPreamble : null
+}
+
 export function stringifyEventDelegation(lines: string[], plan: EventDelegationPlan): void {
   const { containerVar, events, itemLookup, profileComponentName } = plan
   const eventsByName = new Map<string, LoopChildEvent[]>()
@@ -133,7 +153,8 @@ function emitKeyedLookup(
   handlerCall: string,
   lookup: KeyedItemLookup,
 ): void {
-  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) {
     // Single-level keyed lookup.
@@ -146,15 +167,28 @@ function emitKeyedLookup(
       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 (idxLine) ls.push(`          ${idxLine}`)
-      ls.push(`          ${handlerCall}`)
+      // Leading `;` (not just relying on the preceding line's own
+      // semicolon): `handlerCall` always starts with `(` — an ASI hazard
+      // pre-existing in this branch even with neither optional line above
+      // (`const ${param} = __bfLoopItem` has no trailing `;`), which glues
+      // the call onto it as `__bfLoopItem(...)` and throws
+      // `TypeError: __bfLoopItem is not a function`. Defend at the one
+      // emission point rather than chasing every preceding-line shape.
+      ls.push(`          ;${handlerCall}`)
       ls.push(`        }`)
     } else {
+      // The preamble (when referenced) and the handler call both run INSIDE
+      // the item null guard — a `.find()` miss (stale-DOM race, e.g. the
+      // clicked row's key no longer in the current array) must short-circuit
+      // before a preamble that dereferences the item ever runs (BUG-4).
       ls.push(`        const ${param} = ${arrayExpr}.find(item => String(${keyWithItem}) === key)`)
-      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(`      }`)
     return
@@ -187,10 +221,14 @@ function emitKeyedLookup(
   }
   const outerGuard = hasBindings ? '__bfLoopItem' : param
   const allParams = [outerGuard, ...ev.nestedLoops.map(n => n.param)]
-  if (mapPreamble) ls.push(`      ${mapPreamble}`)
+  // Preamble and idx binding run INSIDE the combined item guard (BUG-4) —
+  // a nested `.find()` miss must short-circuit before the preamble runs.
   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(
@@ -199,7 +237,8 @@ function emitDynamicIndexLookup(
   handlerCall: string,
   lookup: DynamicIndexItemLookup,
 ): void {
-  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) {`)
@@ -208,15 +247,19 @@ function emitDynamicIndexLookup(
     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 {
+    // Preamble and idx binding run INSIDE the item null guard (BUG-4) — an
+    // out-of-range index (stale-DOM race) must short-circuit first.
     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(`      }`)
 }
@@ -228,7 +271,8 @@ function emitStaticIndexLookup(
   lookup: StaticIndexItemLookup,
   containerVar: string,
 ): void {
-  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`)
@@ -236,8 +280,12 @@ function emitStaticIndexLookup(
   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}`)
-  if (idxLine) ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`)
-  else ls.push(`        if (${param}) ${handlerCall}`)
+  // Preamble and idx binding run INSIDE the item null guard (BUG-4) — an
+  // out-of-range index (stale-DOM race) must short-circuit first.
+  ls.push(`        if (${param}) {`)
+  if (preambleLine) ls.push(`          ${preambleLine}`)
+  if (idxLine) ls.push(`          ${idxLine}`)
+  ls.push(`          ;${handlerCall}`)
+  ls.push(`        }`)
   ls.push(`      }`)
 }

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

@@ -32,6 +32,7 @@ import { buildSkeletonPathPlan, type SkeletonPathPlan } from './skeleton-paths.t
 import { stringifyComponentLoop } from './component-loop.ts'
 import { stringifyCompositeLoop } from './composite-loop.ts'
 import type { LoopChildRefBinding, LoopPlan, PlainLoopPlan, StaticLoopPlan } from '../plan/types.ts'
+import type { PreambleRegionPlan } from '../plan/loop.ts'
 
 /**
  * Emit `(callback)(__rf)` for each ref on a per-item slot, looking up the
@@ -64,6 +65,40 @@ export function emitLoopChildRefs(
   }
 }
 
+/**
+ * Emit the region-patch effect for each preamble-patched region (#2389 —
+ * `arr.map(t => { const cells = []; ...; return <tr>{cells}<td>{t.name}</td></tr> })`).
+ * The effect re-runs the (loop-param-accessor-wrapped) preamble on every
+ * reactive tick so it re-reads the current per-item signal, recomputes the
+ * region's value, and — past the FIRST run (which only records, trusting
+ * the SSR/CSR mount-time content already in the DOM) — patches the DOM
+ * range via `patchSlotRange(__el, 'sN', html)`. The marker lookup lives
+ * inside `patchSlotRange`, so a row that never changes pays zero lookup
+ * cost at mount/adoption.
+ *
+ * Non-empty `regions` forces the caller's multi-line renderItem layout (the
+ * effect needs `__el` as a query root), mirroring `emitLoopChildRefs`.
+ */
+export function emitPreambleRegionEffects(
+  lines: string[],
+  regions: readonly PreambleRegionPlan[],
+  mapPreambleWrapped: string,
+  opts: { indent: string; elVar: string },
+): void {
+  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}}) }`)
+  }
+}
+
 /**
  * Single dispatch over `LoopPlan` (#1253). Narrows on `plan.kind` and
  * delegates to the per-variant stringifier. Callers should consume this
@@ -128,8 +163,33 @@ export function stringifyPlainLoop(
     bodyIsMultiRoot,
     anchored,
     anchorKeyExpr,
+    preambleRegions,
   } = plan
 
+  // flatMap descriptor mode: the accessor flattens the source through the
+  // callback body (each leaf a `({ k, h })` descriptor), mapArray keys on
+  // `d.k`, and each item element is built from — and patched against — its
+  // rendered HTML. Hydration adopts the SSR leaf in place (`__last` seeds
+  // undefined so the first effect run records without patching — trust SSR,
+  // same contract as plain rows); a later same-key HTML change patches the
+  // element wholesale via `patchLeaf` (flatMap leaves carry no per-slot
+  // wiring by construction — the compiler refuses leaves that would).
+  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
+  }
+
   // Whole-item conditional loops (#1665) render 0-or-1 element per item, so
   // they route through `mapArrayAnchored`. The renderItem returns a fragment
   // headed by a `<!--bf-loop-i:KEY-->` anchor and seeded with the
@@ -158,7 +218,10 @@ export function stringifyPlainLoop(
   // the factory, so non-empty refs force the multi-line layout the same way
   // reactive effects do (#1244).
   const loopBfId = plan.profileLoopId ? `, ${JSON.stringify(plan.profileLoopId)}` : ''
-  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0) {
+  // Preamble-patched regions (#2389) need `__el` as a query root for their
+  // effect, so non-empty regions force the multi-line layout — same
+  // precedent as `childRefs` above.
+  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0 && preambleRegions.length === 0) {
     // Single-line renderItem (no reactive effects, single root, no refs).
     const unwrapInline = paramUnwrap ? `${paramUnwrap} ` : ''
     const preamble = mapPreambleWrapped ? `${mapPreambleWrapped}; ` : ''
@@ -217,6 +280,7 @@ export function stringifyPlainLoop(
     })
   }
   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})`)
 }

package/src/ir-to-client-js/html-template.ts

@@ -2,7 +2,7 @@
  * IR → HTML template string generation and validation.
  */
 
-import type { AttrValue, IRAttribute, IRNode, IRProp, MapCallbackPreamble } from '../types.ts'
+import type { AttrValue, FlatMapCallback, IRAttribute, IRNode, IRProp, MapCallbackPreamble } from '../types.ts'
 import { isBooleanAttr } from '../html-constants.ts'
 import { toHtmlAttrName, attrValueToString, quotePropName, PROPS_PARAM, DATA_BF_PH, keyAttrName, loopStartMarker, loopEndMarker, loopItemMarker, freeIdsFromRefs, setIntersects, wrapExprWithLoopParams } from './utils.ts'
 import type { LoopParamSpec } from './utils.ts'
@@ -276,9 +276,14 @@ function templateAttrExpr(attrName: string, valExpr: string, presenceOrUndefined
   // `data-key` / `data-key-N` is a reconciliation contract — every loop item
   // must carry one. Emit unconditionally; if the user passes `key={undefined}`
   // we want it to surface as `data-key="undefined"` (and ultimately a runtime
-  // assertion in mapArray) rather than silently fall back to "no key".
+  // assertion in mapArray) rather than silently fall back to "no key" —
+  // `escapeAttr(undefined)` stringifies to exactly that. The value is escaped
+  // like every other dynamic attribute: SSR adapters escape it (their
+  // template engines do), so an unescaped `"` in a key — surfaced by the
+  // flatmap-expression-body fixture's adversarial keys — corrupted the
+  // client-assembled HTML and diverged from the SSR bytes.
   if (attrName === 'data-key' || attrName.startsWith('data-key-')) {
-    return `${attrName}="\${${valExpr}}"`
+    return `${attrName}="\${${escapeAttrValueExpr(valExpr)}}"`
   }
   return `\${(${valExpr}) != null ? '${attrName}="' + ${escapeAttrValueExpr(valExpr)} + '"' : ''}`
 }
@@ -575,6 +580,12 @@ export function renderPreamble(
     transformJs?: (text: string) => string
     /** Context-appropriate leaf renderer (an irToHtmlTemplate variant). */
     renderLeaf: (ir: IRNode) => string
+    /**
+     * When true, `renderLeaf` output is spliced verbatim — the renderer
+     * supplies its own delimiters (e.g. the flatMap descriptor form
+     * `({ k, h })`). Default wraps each leaf in a template literal.
+     */
+    rawLeaf?: boolean
   },
 ): string {
   let out = ''
@@ -582,6 +593,8 @@ export function renderPreamble(
     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)) + '`'
     }
@@ -589,6 +602,96 @@ export function renderPreamble(
   return out
 }
 
+/**
+ * Project a flatMap segment leaf's `key={...}` attribute into a runtime key
+ * expression, or `null` when the leaf declares none. Template-literal keys
+ * (`key={\`${it.id}:${tag}\`}`) are first-class here — unlike the loop-level
+ * `extractLoopKey`, the expression is evaluated inside the flatMap body where
+ * the callback params are in scope, so any expression form works.
+ */
+export function flatMapLeafKeyExpr(ir: IRNode): string | null {
+  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
+  }
+}
+
+/** Copy of `ir` with the loop `key` attribute removed (element leaves only). */
+function stripLeafKeyAttr(ir: IRNode): IRNode {
+  if (ir.type !== 'element') return ir
+  return { ...ir, attrs: ir.attrs.filter((a) => a.name !== 'key') }
+}
+
+/**
+ * Render a `FlatMapCallback` as the CLIENT-SIDE descriptor body for
+ * `mapArray` (the reconciliation twin of the string-template rendering in
+ * `irToHtmlTemplate`'s `'loop'` case). Each JSX leaf becomes
+ * `({ k: <keyExpr>, h: \`<html>\` })` — the flatMap flattens descriptors,
+ * `mapArray` keys on `d.k` (index fallback), and the emitted renderItem
+ * builds/patches the leaf element from `d.h`.
+ *
+ * Runs in the init scope where the loop SOURCE items are plain values (the
+ * flatMap executes inside the `mapArray` accessor, BEFORE per-item signals
+ * exist), so neither js segments nor leaf HTML get the accessor wrap — refs
+ * stay `t.title`, not `t().title`. `data-key` is deliberately NOT emitted in
+ * the leaf HTML: reconciliation identity is stamped by `mapArray` via
+ * `setAttribute`, matching the SSR side (which never emits it for flatMap
+ * leaves).
+ */
+export function renderFlatMapClientBody(
+  cb: Pick<FlatMapCallback, 'segments'>,
+  restSpreadNames?: Set<string>,
+): string {
+  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}\` })`
+    },
+  })
+}
+
+/** True when any segment leaf declares a `key` — drives the mapArray keyFn. */
+export function flatMapCallbackHasKeyedLeaf(cb: Pick<FlatMapCallback, 'segments'>): boolean {
+  return cb.segments.some((s) => s.kind === 'jsx' && flatMapLeafKeyExpr(s.ir) !== null)
+}
+
+/**
+ * Synthesize the client descriptor body for a flatMap PROJECTION loop —
+ * one whose only child is a nested `IRLoop` lowered from
+ * `flatMap(it => it.tags.map(tag => <li/>))`. The neutral IR is the single
+ * carrier: SSR adapters templatize the nested loop natively, and this
+ * derives the `mapArray` accessor's flatten projection from the SAME inner
+ * loop — `<chained-inner>.map((tag, i) => ({ k: <inner.key>, h: `<leaf>` }))`.
+ * Runs in the accessor context (plain source items, no per-item signals),
+ * so leaf refs stay unwrapped. Leaf `key` attrs were already stripped at IR
+ * build (`stripLoopLeafKeyAttrs`); the inner loop's `key` FIELD supplies
+ * `k`.
+ */
+export function renderFlatMapProjectionClientBody(
+  inner: Extract<IRNode, { type: 'loop' }>,
+  restSpreadNames?: Set<string>,
+): string {
+  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}\` }))`
+}
+
 /**
  * SSR/CSR escaping parity for preamble leaves, decided once at the door: a
  * JSX-runtime SSR adapter renders the leaf's raw JSX and auto-escapes text
@@ -816,8 +919,12 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       if (node.flatMapCallback) {
         // Complex flatMap: the body is structured segments, rendered through
         // the same single door as map preambles.
+        // Leaf `key` is stripped from the string form: SSR (Hono rawBody)
+        // never emits data-key for flatMap leaves, and reconciliation
+        // identity is stamped by mapArray via setAttribute — emitting it
+        // here was the CSR/SSR data-key asymmetry (unescaped, client-only).
         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) {
@@ -1263,7 +1370,8 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
       let mapExpr: string
       if (node.flatMapCallback) {
         const body = 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} => ${body}).join('')}`
       } else if (node.preamble) {
@@ -2386,7 +2494,8 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         const body = 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} => ${body}).join('')}`
       } else if (node.preamble) {

package/src/ir-to-client-js/imports.ts

@@ -8,7 +8,7 @@ import { isClientBuiltinName } from '../builtins.ts'
 // All exports from @barefootjs/client/runtime that may be used in generated code
 export const RUNTIME_IMPORT_CANDIDATES = [
   'createSignal', 'createMemo', 'createEffect', 'onCleanup', 'onMount',
-  'hydrate', 'insert', 'reconcileElements', 'getLoopChildren', 'getLoopNodes', 'mapArray', 'mapArrayAnchored', 'createDisposableEffect',
+  'hydrate', 'insert', 'reconcileElements', 'getLoopChildren', 'getLoopNodes', 'mapArray', 'mapArrayAnchored', 'patchLeaf', 'patchSlotRange', 'createDisposableEffect',
   'createComponent', 'renderChild', 'registerComponent', 'registerTemplate', 'initChild', 'upsertChild', 'updateClientMarker',
   'createPortal',
   'provideContext', 'createContext', 'useContext',

package/src/ir-to-client-js/reactivity.ts

@@ -570,6 +570,12 @@ export function collectLoopChildReactiveTexts(
     ...stopAt<boolean>('loop', 'async', 'ifStatement'),
     expression: ({ node: n, scope: insideConditional }) => {
       if (!n.slotId) return
+      // #2389 — a preamble-patched region (see `IRLoop.preambleRegions`) has
+      // its own `patchSlotRange`-based effect (`preambleRegions` in the
+      // client-JS loop plan); it must never ALSO become a `reactiveTexts`
+      // entry, which would patch it via `.textContent` and corrupt markup
+      // (a `joinArrayChild` region's value is raw HTML, not text).
+      if (n.preambleRegion) return
       const originFreeIds = freeIdsFromRefs(n.origin?.freeRefs)
       const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds)
       // Include if expression reads signals OR references the loop parameter

package/src/ir-to-client-js/types.ts

@@ -23,6 +23,7 @@ import type {
   TypeInfo,
   TypeDefinition,
   MapCallbackPreamble,
+  PreambleRegionSource,
 } from '../types.ts'
 import type { CsrInlinabilityMap } from './csr-substitute.ts'
 import type { SkeletonSlotPaths } from './html-template.ts'
@@ -310,6 +311,29 @@ export interface LoopCore {
    * `IRLoop.objectIteration`.
    */
   objectIteration?: 'entries' | 'keys' | 'values'
+
+  /**
+   * Client-side descriptor body for a flatMap loop carried as structured
+   * segments (`IRLoop.flatMapCallback`). `body` is the callback body
+   * rendered so each JSX leaf becomes a `({ k, h })` descriptor
+   * (`renderFlatMapClientBody`); the plan builder wires
+   * `mapArray(() => <chained>.flatMap(<params> => <body>), …)` so the
+   * runtime reconciles the FLATTENED leaves — never the un-flattened
+   * source items (which loses leaves at hydration and crashes on adds
+   * against an empty item template). `keyed` is true when any leaf
+   * declares a `key`, driving the `d.k`-based keyFn.
+   */
+  flatMapClient?: { params: string; body: string; keyed: boolean }
+
+  /**
+   * Loop-body expression children classified as preamble-patched regions
+   * (#2389), threaded from `IRLoop.preambleRegions`. Consumed only by the
+   * top-level and branch **plain** loop-plan builders (`build-loop.ts`,
+   * `build-branch-loop.ts`) — the composite / component / static / anchored
+   * shapes leave this unconsumed (stale — same pre-existing freeze, not a
+   * new regression) pending a follow-up.
+   */
+  preambleRegions?: readonly PreambleRegionSource[]
 }
 
 /**