@barefootjs/jsx 0.26.1 → 0.26.3

package/src/ir-to-client-js/control-flow/plan/build-inner-loop.ts

@@ -29,6 +29,7 @@ import {
   attrValueToString,
 } from '../../utils.ts'
 import { buildChildRefBindings, buildStaticChildRefBindings } from '../shared.ts'
+import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 
 /**
  * Mirror of the helper in `build-loop-child-arm.ts` — kept local to avoid
@@ -115,7 +116,7 @@ export function buildInnerLoopsPlan(args: BuildInnerLoopsArgs): InnerLoopsPlan {
     const useReactive = refsParent && !!inner.template
 
     const emit: InnerLoopReactiveEmit | InnerLoopStaticEmit = useReactive
-      ? buildReactiveEmit(inner, level, wrapOuter, uidSuffix)
+      ? buildReactiveEmit(inner, level, wrapOuter, uidSuffix, outerLoopParam, outerLoopParamBindings)
       : buildStaticEmit(inner, level, uidSuffix)
 
     const arrayExpr = useReactive ? wrapOuter(inner.array) : inner.array
@@ -155,6 +156,8 @@ function buildReactiveEmit(
   level: DepthLevel,
   wrapOuter: (expr: string) => string,
   uidSuffix: string,
+  outerLoopParam?: string,
+  outerLoopParamBindings?: readonly LoopParamBinding[],
 ): InnerLoopReactiveEmit {
   const wrapInner = (expr: string) => wrapLoopParamAsAccessor(expr, inner.param, inner.paramBindings)
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(inner.param, inner.paramBindings)
@@ -229,7 +232,20 @@ function buildReactiveEmit(
   const indexAlias = nestedLoopIndexAlias(inner, `__innerIdx${uidSuffix}`, paramHead, level.comps, level.events)
   if (indexAlias) preludeStatements.push(indexAlias)
   if (paramUnwrap) preludeStatements.push(paramUnwrap)
-  if (inner.mapPreamble) preludeStatements.push(wrapInner(wrapOuter(inner.mapPreamble)))
+  if (inner.preamble) {
+    // Leaf JSX renders under both param contexts, mirroring the
+    // wrapInner(wrapOuter(...)) applied to the js text.
+    const leafLoopParams = outerLoopParam
+      ? [
+          { param: outerLoopParam, bindings: outerLoopParamBindings },
+          { param: inner.param, bindings: inner.paramBindings },
+        ]
+      : [{ param: inner.param, bindings: inner.paramBindings }]
+    preludeStatements.push(renderPreamble(inner.preamble, {
+      transformJs: (t) => wrapInner(wrapOuter(t)),
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, leafLoopParams, undefined, true),
+    }))
+  }
 
   const childRefs = buildChildRefBindings(inner.bindings.refs, inner.param, inner.paramBindings)
 
@@ -265,7 +281,14 @@ function buildStaticEmit(inner: NestedLoop, level: DepthLevel, uidSuffix: string
   const preludeStatements: string[] = []
   const indexAlias = nestedLoopIndexAlias(inner, `__innerIdx${uidSuffix}`, inner.param, level.comps, level.events)
   if (indexAlias) preludeStatements.push(indexAlias)
-  if (inner.mapPreamble) preludeStatements.push(inner.mapPreamble)
+  // Static `forEach` receives the literal item, so neither the js text nor a
+  // leaf's param reads get accessor-wrapped (mirrors the verbatim emission
+  // of the js segments above).
+  if (inner.preamble) {
+    preludeStatements.push(renderPreamble(inner.preamble, {
+      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true),
+    }))
+  }
   return {
     mode: 'static',
     rawKey: inner.key ?? null,

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

@@ -39,6 +39,7 @@ import {
 import { buildLoopReactiveEffectsPlan } from './build-reactive-effects.ts'
 import { buildComponentLoopPlan } from './build-component-loop.ts'
 import { buildTopLevelCompositePlan } from './build-composite-loop.ts'
+import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
   LoopPlan,
   PlainLoopPlan,
@@ -92,6 +93,7 @@ export function buildPlainLoopPlan(elem: TopLevelLoop, profileComponentName?: st
 
   return {
     kind: 'plain',
+    rowConstruction: 'string-template',
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${elem.slotId}` : undefined,
@@ -100,7 +102,15 @@ export function buildPlainLoopPlan(elem: TopLevelLoop, profileComponentName?: st
     paramHead,
     paramUnwrap,
     indexParam: elem.index || '__idx',
-    mapPreambleWrapped: elem.mapPreamble ? wrap(elem.mapPreamble) : '',
+    // Stage 3 / D4 — js segments get the loop-param accessor wrap; jsx leaves
+    // render as HTML-string templates under this loop's param context so a
+    // leaf that reads the item (`r`) becomes `r()`.
+    mapPreambleWrapped: elem.preamble
+      ? renderPreamble(elem.preamble, {
+          transformJs: wrap,
+          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true),
+        })
+      : '',
     template: elem.template,
     skeletonTemplate: elem.skeletonTemplate,
     skeletonPaths: elem.skeletonPaths,
@@ -139,6 +149,7 @@ export function buildStaticLoopPlan(elem: TopLevelLoop, unsafeLocalNames: Set<st
 
   return {
     kind: 'static',
+    rowConstruction: 'string-template',
     containerVar: `_${varSlotId(elem.slotId)}`,
     arrayExpr: elem.array,
     param: elem.param,
@@ -188,7 +199,11 @@ function buildStaticLoopMaterialize(
   if (!setIntersects(elem.arrayFreeIdentifiers, unsafeLocalNames)) return null
   return {
     itemTemplate: elem.staticItemTemplate,
-    mapPreamble: elem.mapPreamble ?? '',
+    mapPreamble: elem.preamble
+      ? renderPreamble(elem.preamble, {
+          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true),
+        })
+      : '',
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,
   }
 }

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

@@ -45,6 +45,18 @@ interface LoopPlanCommon {
    * — initial mount, SSR hydration, and same-key remount after unmount.
    */
   childRefs: readonly LoopChildRefBinding[]
+  /**
+   * How this variant constructs each row's DOM (Stage 3 root cure,
+   * spec/callback-fidelity.md). `'string-template'` = rows are built from
+   * interpolated innerHTML template literals, so a `.map()` preamble carrying
+   * lowered JSX leaves can be spliced via `renderPreamble()`. `'dom-ops'` =
+   * rows are built imperatively (createElement/reconcile paths) and CANNOT
+   * host a string-lowered preamble — the plan dispatcher refuses a JSX-bearing
+   * preamble on such a variant instead of letting it drop silently. Required
+   * on every variant (like `childRefs`) so a new loop shape must declare its
+   * capability — the compile error is the point.
+   */
+  rowConstruction: 'string-template' | 'dom-ops'
 }
 
 /** Fields shared by every dynamic (`mapArray`-driven) loop variant. */

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

@@ -14,6 +14,7 @@
 
 import type { LoopChildEvent, LoopChildRef, TopLevelLoop, NestedLoop, CollectedLoop } from '../types.ts'
 import type { IRLoopChildComponent, LoopParamBinding } from '../../types.ts'
+import { preambleAnalysisText } from '../../types.ts'
 import { quotePropName, wrapLoopParamAsAccessor, irChildrenFreeIds, attrValueToString } from '../utils.ts'
 import { irChildrenToJsExpr } from '../html-template.ts'
 import { emitListenerBlock } from './stringify/event-listener.ts'
@@ -83,7 +84,7 @@ export function nestedLoopReferencesIndex(
   for (const a of inner.bindings.reactiveAttrs) {
     if (exprRefs(a.expression, a.freeIdentifiers)) return true
   }
-  if (inner.mapPreamble && extractFreeIdentifiersFromStatementText(inner.mapPreamble).has(index)) return true
+  if (inner.preamble && extractFreeIdentifiersFromStatementText(preambleAnalysisText(inner.preamble)).has(index)) return true
   if (inner.template && extractFreeIdentifiersFromTemplateText(inner.template).has(index)) return true
   for (const ev of events) {
     if (exprRefs(ev.handler)) return true

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

@@ -6,7 +6,7 @@
  *     if (<container>) <container>.addEventListener('<eventName>', (__bfEvt) => {
  *       const target = __bfEvt.target
  *       const <slot>El = target.closest('[bf="<slotId>"]')
- *       if (<slot>El) {
+ *       if (<slot>El && <container>.contains(<slot>El)) {
  *         <item-lookup specific>
  *         <handlerCall>
  *         return
@@ -94,8 +94,15 @@ export function stringifyEventDelegation(lines: string[], plan: EventDelegationP
     lines.push(`    const target = __bfEvt.target`)
     for (const ev of evs) {
       const childVar = varSlotId(ev.childSlotId)
+      // Bound the slot match to the delegating container (#2367). `bf` ids are
+      // unique only *within* a component, so an unscoped
+      // `target.closest('[bf="sN"]')` can match a same-id element in an ancestor
+      // component and silently take the wrong branch. The container holds every
+      // slot it delegates on, so a same-id ancestor is never a descendant of it —
+      // the `container.contains(...)` guard rejects the foreign match and the
+      // handler falls through to the correct branch.
       lines.push(`    const ${childVar}El = target.closest('[bf="${ev.childSlotId}"]')`)
-      lines.push(`    if (${childVar}El) {`)
+      lines.push(`    if (${childVar}El && ${containerVar}.contains(${childVar}El)) {`)
       const handlerCall = withTurn(`(${ev.handler.trim()})(__bfEvt)`, profileComponentName, ev.childSlotId, ev.eventName)
       switch (itemLookup.kind) {
         case 'keyed':

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

@@ -21,6 +21,7 @@
  */
 
 import type { ClientJsContext, TopLevelLoop } from './types.ts'
+import { internalInvariant } from '../errors.ts'
 import { buildInsertPlan } from './control-flow/plan/build-insert.ts'
 import { stringifyInsert } from './control-flow/stringify/insert.ts'
 import { buildLoopPlan } from './control-flow/plan/build-loop.ts'
@@ -70,6 +71,16 @@ export function emitLoopUpdates(lines: string[], ctx: ClientJsContext, unsafeLoc
       unsafeLocalNames,
       profileComponentName: ctx.profile ? ctx.componentName : undefined,
     })
+    // Stage 3 root cure — a JSX-bearing preamble can only be spliced into a
+    // string-templated row (renderPreamble). Every shape that reaches a
+    // 'dom-ops' variant today is already refused in Phase 1 with a proper
+    // source location; this backstop exists for FUTURE variants, so a new
+    // plan kind that declares 'dom-ops' cannot silently drop the preamble —
+    // it fails the build here instead.
+    internalInvariant(
+      !(elem.preamble && elem.preamble.builderNames.length > 0 && plan.rowConstruction === 'dom-ops'),
+      `loop variant '${plan.kind}' declares dom-ops row construction but received a JSX-bearing preamble — add a Phase-1 refusal (or wire renderPreamble support) for this shape`,
+    )
     stringifyLoop(lines, plan)
     emitLoopEventDelegation(lines, elem, plan.kind, ctx.profile ? ctx.componentName : undefined)
   }

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, 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'
@@ -556,6 +556,71 @@ 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
+  },
+): 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 {
+      out += '`' + opts.renderLeaf(escapeLeafTextExpressions(seg.ir)) + '`'
+    }
+  }
+  return out
+}
+
+/**
+ * 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 +689,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 +814,17 @@ 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.
+        const body = renderPreamble(node.flatMapCallback, {
+          renderLeaf: (ir) => irToHtmlTemplate(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 +1214,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 +1262,14 @@ 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, {
+          renderLeaf: (ir) => irToPlaceholderTemplate(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 +1635,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 +2222,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 +2379,20 @@ 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),
+          renderLeaf: (ir) => recurseInLoopBody(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/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/types.ts

@@ -22,6 +22,7 @@ import type {
   ImportInfo,
   TypeInfo,
   TypeDefinition,
+  MapCallbackPreamble,
 } from '../types.ts'
 import type { CsrInlinabilityMap } from './csr-substitute.ts'
 import type { SkeletonSlotPaths } from './html-template.ts'
@@ -356,7 +357,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 +443,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 +600,7 @@ export interface TopLevelLoop extends LoopCore {
     raw: string  // Full comparator body for client JS
   }
   chainOrder?: 'filter-sort' | 'sort-filter'
-  mapPreamble?: string
+  preamble?: MapCallbackPreamble
 }
 
 /**