@barefootjs/jsx 0.26.2 → 0.26.4

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 } 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)} + '"' : ''}`
 }
@@ -556,6 +561,169 @@ function itemAnchorTemplate(keyExpr: string): string {
   return `<!--${loopItemMarker('${' + keyExpr + '}')}-->`
 }
 
+/**
+ * The ONLY door from a structured `.map()` preamble to emitted text (Stage 3
+ * root cure, spec/callback-fidelity.md). `js` segments contribute their JS
+ * text (template variant when requested, then the caller's context transform —
+ * e.g. the loop-param accessor wrap); `jsx` segments render their compiled IR
+ * as a template-literal HTML string. There is no sentinel substitution because
+ * there is no sentinel: mixed content stays structured until this function.
+ * Emitters that cannot host a string-templated preamble must not call this —
+ * they refuse at plan dispatch instead of splicing.
+ */
+export function renderPreamble(
+  preamble: Pick<MapCallbackPreamble, 'segments'>,
+  opts: {
+    /** Pick `templateText` on js segments (hydrate/CSR template contexts). */
+    textVariant?: 'client' | 'template'
+    /** Context transform for js text (e.g. wrapLoopParamAsAccessor). */
+    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 = ''
+  for (const seg of preamble.segments) {
+    if (seg.kind === 'js') {
+      const text = opts.textVariant === 'template' ? (seg.templateText ?? seg.text) : seg.text
+      out += opts.transformJs ? opts.transformJs(text) : text
+    } else if (opts.rawLeaf) {
+      out += opts.renderLeaf(escapeLeafTextExpressions(seg.ir))
+    } else {
+      out += '`' + opts.renderLeaf(escapeLeafTextExpressions(seg.ir)) + '`'
+    }
+  }
+  return out
+}
+
+/**
+ * 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
+ * interpolations (`{c}`), so the client's HTML-string lowering must escape the
+ * same positions — wrap every text-position expression in `escapeText(...)`.
+ * Pure (returns a transformed copy); the neutral IR is never mutated with a
+ * client-only concern. Attribute values already flow through the template
+ * emitters' own attr escaping.
+ */
+function escapeLeafTextExpressions(ir: IRNode): IRNode {
+  switch (ir.type) {
+    case 'element':
+      return { ...ir, children: ir.children.map(escapeLeafTextExpressions) }
+    case 'fragment':
+      return { ...ir, children: ir.children.map(escapeLeafTextExpressions) }
+    case 'expression': {
+      if (ir.expr === 'null' || ir.expr === 'undefined') return ir
+      // Already-wrapped or slotted expressions keep their existing handling.
+      if (ir.slotId || ir.expr.trimStart().startsWith('escapeText(')) return ir
+      return { ...ir, expr: `escapeText((${ir.expr}))`, templateExpr: ir.templateExpr ? `escapeText((${ir.templateExpr}))` : ir.templateExpr }
+    }
+    case 'conditional':
+      return {
+        ...ir,
+        whenTrue: escapeLeafTextExpressions(ir.whenTrue),
+        whenFalse: ir.whenFalse ? escapeLeafTextExpressions(ir.whenFalse) : ir.whenFalse,
+      }
+    default:
+      return ir
+  }
+}
+
 export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>, branchSlotsVar?: string, insideLoop = false, inHoistedChildren = false): string {
   const recurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, insideLoop, inHoistedChildren)
   const wrapExpr = (expr: string) => wrapExprWithLoopParams(expr, loopParams)
@@ -624,20 +792,29 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       // as HTML (template.innerHTML), so re-escape for the HTML parser.
       return escapeHtml(node.value)
 
-    case 'expression':
+    case 'expression': {
       if (node.expr === 'null' || node.expr === 'undefined') return ''
+      const inner = wrapInterpolation(wrapExpr(node.expr))
+      // Stage 3 / D4 — an element-array child ({out}) built by an arbitrary
+      // .map() preamble is an array of HTML strings; join it rather than let
+      // `${[...]}` `String`-comma-collapse it. Only reached on a JS-runtime
+      // adapter (the flag is set in Phase 1 only there); a plain local can be
+      // read twice safely.
+      const valueExpr = node.joinArrayChild
+        ? `Array.isArray(${inner}) ? ${inner}.join('') : (${inner} ?? '')`
+        : inner
       if (node.slotId) {
-        const inner = wrapInterpolation(wrapExpr(node.expr))
         // In branch-slot context `wrapInterpolation` routes the value
         // through `__bfSlot`, which returns raw `<!--bf-slot:N-->` markers
         // for live `Node` values (spliced back by `insert()`). Escaping
         // would corrupt those markers and drop slotted content (#1694
         // regression). `__bfSlot` owns coercion of its own value, so the
         // text-escape applies only to the non-slot (plain text) form.
-        const slotted = branchSlotsVar ? inner : escapeTextSlotExpr(inner)
+        const slotted = branchSlotsVar || node.joinArrayChild ? valueExpr : escapeTextSlotExpr(valueExpr)
         return `<!--bf:${node.slotId}-->\${${slotted}}<!--/-->`
       }
-      return `\${${wrapInterpolation(wrapExpr(node.expr))}}`
+      return `\${${valueExpr}}`
+    }
 
     case 'conditional': {
       const trueBranch = recurse(node.whenTrue)
@@ -740,15 +917,21 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       let mapExpr: string
 
       if (node.flatMapCallback) {
-        // Complex flatMap: use pre-compiled body with JSX placeholders
-        let body = node.flatMapCallback.templateBody ?? node.flatMapCallback.body
-        for (const frag of node.flatMapCallback.fragments) {
-          const renderedIr = irToHtmlTemplate(frag.ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop)
-          body = body.replace(frag.placeholder, `\`${renderedIr}\``)
-        }
+        // 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(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop),
+        })
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
-      } else if (node.mapPreamble) {
-        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`
+      } else if (node.preamble) {
+        // Stage 3 / D4 — render JSX leaves in an arbitrary array-builder
+        // preamble (the hydrate-template context uses the bare loop param).
+        const preamble = renderPreamble(node.preamble, { textVariant: 'client', renderLeaf: (ir) => irToHtmlTemplate(ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop) })
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`
       } else {
         mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`
       }
@@ -1138,12 +1321,18 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
       // as HTML (template.innerHTML), so re-escape for the HTML parser.
       return escapeHtml(node.value)
 
-    case 'expression':
+    case 'expression': {
       if (node.expr === 'null' || node.expr === 'undefined') return ''
+      const wrapped = wrapExpr(node.expr)
+      // Stage 3 / D4 — join an element-array child ({out}) built by the preamble.
+      const value = node.joinArrayChild
+        ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')`
+        : wrapped
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(wrapExpr(node.expr))}}<!--/-->`
+        return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped)}}<!--/-->`
       }
-      return `\${${wrapExpr(node.expr)}}`
+      return `\${${value}}`
+    }
 
     case 'conditional': {
       const trueBranch = recurse(node.whenTrue)
@@ -1180,14 +1369,15 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
       const iterMethod = node.method ?? 'map'
       let mapExpr: string
       if (node.flatMapCallback) {
-        let body = node.flatMapCallback.templateBody ?? node.flatMapCallback.body
-        for (const frag of node.flatMapCallback.fragments) {
-          const renderedIr = irToPlaceholderTemplate(frag.ir, restSpreadNames, loopDepth + 1, loopParams)
-          body = body.replace(frag.placeholder, `\`${renderedIr}\``)
-        }
+        const body = renderPreamble(node.flatMapCallback, {
+          // 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.mapPreamble) {
-        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`
+      } else if (node.preamble) {
+        // Stage 3 / D4 — render JSX leaves in an arbitrary array-builder preamble.
+        const preamble = renderPreamble(node.preamble, { textVariant: 'client', renderLeaf: (ir) => irToPlaceholderTemplate(ir, restSpreadNames, loopDepth + 1, loopParams) })
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`
       } else {
         mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`
       }
@@ -1553,12 +1743,18 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
       // as HTML (template.innerHTML), so re-escape for the HTML parser.
       return escapeHtml(node.value)
 
-    case 'expression':
+    case 'expression': {
       if (node.expr === 'null' || node.expr === 'undefined') return ''
+      const wrapped = transformExpr(node.expr, node.templateExpr)
+      // Stage 3 / D4 — join an element-array child ({out}) built by the preamble.
+      const value = node.joinArrayChild
+        ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')`
+        : wrapped
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(transformExpr(node.expr, node.templateExpr))}}<!--/-->`
+        return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped)}}<!--/-->`
       }
-      return `\${${transformExpr(node.expr, node.templateExpr)}}`
+      return `\${${value}}`
+    }
 
     case 'conditional': {
       // A client-only conditional (auto-deferred brand read or manual
@@ -2134,10 +2330,14 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         // before init's createEffect overwrites the slot (#1128). Emit
         // an empty placeholder instead.
         const expr = transformed === UNSAFE_TEMPLATE_EXPR ? "''" : transformed
+        // Stage 3 / D4 — join an element-array child ({out}) built by the preamble.
+        const value = node.joinArrayChild
+          ? `Array.isArray(${expr}) ? ${expr}.join('') : (${expr} ?? '')`
+          : expr
         if (node.slotId) {
-          return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(expr)}}<!--/-->`
+          return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(expr)}}<!--/-->`
         }
-        return `\${${expr}}`
+        return `\${${value}}`
       }
 
     case 'conditional': {
@@ -2287,16 +2487,21 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
       const iterMethod = node.method ?? 'map'
       let mapExpr: string
       if (node.flatMapCallback) {
-        let body = node.flatMapCallback.templateBody ?? node.flatMapCallback.body
-        for (const frag of node.flatMapCallback.fragments) {
-          const renderedIr = recurseInLoopBody(frag.ir)
-          body = body.replace(frag.placeholder, `\`${renderedIr}\``)
-        }
-        body = applyPropsRewrite(body, propsObjectName ?? null)
+        // Module-scope template context: pick the templateText variant
+        // (destructured-prop refs rewritten to _p.xxx) and apply the
+        // props-object rewrite to js segments only — a rendered leaf handles
+        // its own props context via recurseInLoopBody.
+        const body = renderPreamble(node.flatMapCallback, {
+          textVariant: 'template',
+          transformJs: (t) => applyPropsRewrite(t, propsObjectName ?? null),
+          // Leaf `key` stripped — see the irToHtmlTemplate site above.
+          renderLeaf: (ir) => recurseInLoopBody(stripLeafKeyAttr(ir)),
+        })
         mapExpr = `\${${iterArrayExpr}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
-      } else if (node.mapPreamble) {
-        const rawPreamble = node.templateMapPreamble ?? node.mapPreamble
-        const preamble = applyPropsRewrite(rawPreamble, propsObjectName ?? null)
+      } else if (node.preamble) {
+        // Stage 3 / D4 — template-variant js text with the props rewrite
+        // applied per segment; JSX leaves render via the loop-body recursion.
+        const preamble = renderPreamble(node.preamble, { textVariant: 'template', transformJs: (t) => applyPropsRewrite(t, propsObjectName ?? null), renderLeaf: (ir) => recurseInLoopBody(ir) })
         mapExpr = `\${${iterArrayExpr}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`
       } else {
         mapExpr = `\${${iterArrayExpr}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`

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/plan/build-static-array-child-init.ts

@@ -17,11 +17,23 @@
  * stringifier never inspects raw IR.
  */
 
-import type { IRLoopChildComponent } from '../../types.ts'
-import type { NestedLoop, TopLevelLoop } from '../types.ts'
-import type { ClientJsContext } from '../types.ts'
+import type { IRLoopChildComponent, MapCallbackPreamble } from '../../types.ts'
+import type { ClientJsContext, NestedLoop, TopLevelLoop } from '../types.ts'
 import { quotePropName, varSlotId, attrValueToString, buildLoopChildIndexExpr } from '../utils.ts'
-import { irChildrenToJsExpr } from '../html-template.ts'
+import { irChildrenToJsExpr, renderPreamble, irToHtmlTemplate } from '../html-template.ts'
+
+/**
+ * Render a loop preamble for the static-array init context. Static `forEach`
+ * binds params as plain values (see `buildStaticPropsExpr` note), so neither
+ * js text nor leaf-JSX param reads get accessor-wrapped.
+ */
+function staticPreludeStatements(preamble: MapCallbackPreamble | undefined): string[] {
+  return preamble
+    ? [renderPreamble(preamble, {
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true),
+      })]
+    : []
+}
 import { buildCompSelector } from '../control-flow/shared.ts'
 
 /** The inline prop shape carried on `IRLoopChildComponent.props`. */
@@ -94,7 +106,7 @@ function buildSingleCompPlan(
     arrayExpr: elem.array,
     param: elem.param,
     indexParam: elem.index || '__idx',
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     propsExpr: buildStaticPropsExpr(props),
   }
 }
@@ -113,7 +125,7 @@ function buildOuterNestedPlan(
     param: elem.param,
     indexParam,
     offsetExpr: buildLoopChildIndexExpr(indexParam, elem.offset),
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     propsExpr: buildStaticPropsExpr(comp.props),
   }
 }
@@ -142,13 +154,13 @@ function buildInnerLoopNestedPlan(
     outerParam: elem.param,
     outerIndexParam,
     outerOffsetExpr: buildLoopChildIndexExpr(outerIndexParam, elem.offset),
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     innerContainerSlotId: innerLoop.containerSlotId ?? null,
     innerArrayExpr: innerLoop.array,
     innerParam: innerLoop.param,
     innerIndexParam,
     innerOffsetExpr: buildLoopChildIndexExpr(innerIndexParam, innerLoop.offset),
-    innerPreludeStatements: innerLoop.mapPreamble ? [innerLoop.mapPreamble] : [],
+    innerPreludeStatements: staticPreludeStatements(innerLoop.preamble),
     depth: innerLoop.depth,
     comps,
   }
@@ -189,11 +201,11 @@ function buildComponentRootedInnerLoopPlan(
     // position, so there's no synthetic fallback and index-less loops keep
     // byte-identical output.
     outerIndexParam: elem.index,
-    outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
+    outerPreludeStatements: staticPreludeStatements(elem.preamble),
     innerArrayExpr: innerLoop.array,
     innerParam: innerLoop.param,
     innerIndexParam: innerLoop.index,
-    innerPreludeStatements: innerLoop.mapPreamble ? [innerLoop.mapPreamble] : [],
+    innerPreludeStatements: staticPreludeStatements(innerLoop.preamble),
     depth: innerLoop.depth,
     comps,
   }

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

@@ -22,6 +22,8 @@ import type {
   ImportInfo,
   TypeInfo,
   TypeDefinition,
+  MapCallbackPreamble,
+  PreambleRegionSource,
 } from '../types.ts'
 import type { CsrInlinabilityMap } from './csr-substitute.ts'
 import type { SkeletonSlotPaths } from './html-template.ts'
@@ -309,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[]
 }
 
 /**
@@ -356,7 +381,7 @@ export interface BranchLoop extends LoopCore {
   index: string | null // Index parameter (e.g., 'i')
   template: string     // HTML template for each item
   containerSlotId: string // bf slot ID of the container element (e.g., 's1' for <ul bf="s1">)
-  mapPreamble: string | null
+  preamble?: MapCallbackPreamble
   // Composite loop fields (loops whose body contains child components)
   nestedComponents?: IRLoopChildComponent[]
   innerLoops?: NestedLoop[]
@@ -442,7 +467,7 @@ export interface NestedLoop extends LoopCore {
    * `renderItem` callback so locals referenced by the cloned-template IIFE
    * (and any subsequent reads) are in scope (#1052).
    */
-  mapPreamble?: string
+  preamble?: MapCallbackPreamble
   /** Whether the inner array references the outer loop param (needs reactive mapArray) */
   refsOuterParam?: boolean
   /** Child components inside inner loop items (for initChild/createComponent) */
@@ -599,7 +624,7 @@ export interface TopLevelLoop extends LoopCore {
     raw: string  // Full comparator body for client JS
   }
   chainOrder?: 'filter-sort' | 'sort-filter'
-  mapPreamble?: string
+  preamble?: MapCallbackPreamble
 }
 
 /**