@barefootjs/jsx 0.26.3 → 0.26.4

package/src/ir-to-client-js/collect-elements.ts

@@ -6,7 +6,7 @@ import { type IRNode, type IRElement, type IRComponent, type IRLoop, type IRProp
 import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, LoopOffset, NestedLoop } from './types.ts'
 import { attrValueToString, freeIdsFromRefs, quotePropName, PROPS_PARAM } from './utils.ts'
 import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings } from './reactivity.ts'
-import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, type SkeletonSlotPaths } from './html-template.ts'
+import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, renderFlatMapClientBody, renderFlatMapProjectionClientBody, flatMapCallbackHasKeyedLeaf, type SkeletonSlotPaths } from './html-template.ts'
 import { templateRootIsSvg } from './control-flow/stringify/template-parse.ts'
 import { expandDynamicPropValue, expandConstantForReactivity } from './prop-handling.ts'
 import { walkIR, stopAt } from './walker.ts'
@@ -650,10 +650,26 @@ export function collectElements(
       // are extracted explicitly below for the closure capture set.
       if (!l.slotId || inCond) return
 
+      // flatMap PROJECTION loop: the only child is a nested IRLoop lowered
+      // from `flatMap(it => it.tags.map(...))`. The children exist for SSR
+      // templatization (nested {{range}} on DSL adapters); the CLIENT
+      // reconciles the flattened leaves through the descriptor mapArray
+      // path synthesized from the same inner loop, so none of the
+      // children-derived client machinery (bindings, inner-loop plans,
+      // per-row template) applies — leaf wiring was refused at IR build.
+      const projectionInner =
+        l.method === 'flatMap' && l.children.length === 1 && l.children[0].type === 'loop'
+          ? l.children[0]
+          : undefined
+
       const childHandlers: string[] = []
-      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) {
@@ -668,7 +684,9 @@ export function collectElements(
       // Determine rendering strategy for dynamic arrays:
       // Use element reconciliation when the loop body has nested components,
       // or when inner loops need their own mapArray for events/reactive text.
-      const { useElementReconciliation, innerLoops } = decideLoopRendering(l, siblingOffsets, ctx)
+      const { useElementReconciliation, innerLoops } = projectionInner
+        ? { useElementReconciliation: false, innerLoops: undefined }
+        : decideLoopRendering(l, siblingOffsets, ctx)
 
       let template = ''
       let staticItemTemplate: string | undefined
@@ -691,7 +709,7 @@ export function collectElements(
           // `data-key`, mirroring the SSR template's renderChild emit.
           staticItemTemplate = irToHtmlTemplate(l.children[0], buildRestSpreadNames(ctx), 0, undefined, undefined, /* insideLoop */ true)
         }
-      } else if (l.children[0]) {
+      } else if (l.children[0] && !projectionInner) {
         // Pass loopParams so expressions are wrapped at generation time,
         // avoiding post-hoc regex wrapping that corrupts literal attribute values.
         // Forward destructured bindings (#951) so references like `cfg.color`
@@ -777,6 +795,20 @@ export function collectElements(
         } : undefined,
         chainOrder: l.chainOrder,
         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,
       })
       // Don't descend — loop-scoped variables are only available inside the iteration.
     },
@@ -1069,8 +1101,16 @@ function collectBranchLoops(
       // reactive-text collection on inner loops reached from this call path
       // is handled at the enclosing branch-loop level below (`if (ctx)` block
       // around `collectLoopChildReactiveTexts`), not per inner loop.
-      const { useElementReconciliation, innerLoops: innerLoopsCollected } =
-        decideLoopRendering(n, siblingOffsets, undefined)
+      // flatMap PROJECTION loop — see the top-level handler's note: children
+      // are SSR-only; the client rides the descriptor mapArray path.
+      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)
 
       // Build the item template from loop children.
       // Use loopDepth=0: this loop gets its own reconcileElements (independent
@@ -1080,7 +1120,9 @@ function collectBranchLoops(
       // use `param()` to read the current item value.
       let childTemplate: string
       const branchLoopParamSpec = [{ param: n.param, bindings: n.paramBindings }]
-      if (useElementReconciliation && n.children[0]) {
+      if (projectionInner) {
+        childTemplate = '' // descriptor renderItem builds from d.h, not a row template
+      } 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('')
@@ -1092,7 +1134,7 @@ function collectBranchLoops(
       // memos). Previously these were only collected for composite loops,
       // which caused reactive reads inside simple loop bodies to silently
       // no-op for existing items.
-      const branchBindings = ctx
+      const branchBindings = ctx && !projectionInner
         ? collectLoopChildBindings(n.children, ctx, siblingOffsets, n.param, n.paramBindings)
         : emptyLoopChildBindings()
 
@@ -1112,6 +1154,7 @@ function collectBranchLoops(
         template: childTemplate,
         containerSlotId: containerSlot,
         preamble: n.preamble,
+        preambleRegions: n.preambleRegions,
         nestedComponents: useElementReconciliation ? n.nestedComponents : undefined,
         bindings: branchBindings,
         innerLoops: useElementReconciliation ? innerLoopsCollected : undefined,
@@ -1126,6 +1169,19 @@ function collectBranchLoops(
           raw: n.sortComparator.raw,
         } : undefined,
         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,
       })
       // Don't recurse into the loop — nested loops are handled by the loop's own reconciliation.
     },

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

@@ -15,11 +15,17 @@
  * pair.
  */
 
-import type { CompositeLoopPlan, LoopChildRefBinding } from './loop.ts'
+import type { CompositeLoopPlan, LoopChildRefBinding, PreambleRegionPlan } from './loop.ts'
 import type { EventDelegationPlan } from './event-delegation.ts'
 import type { ReactiveEffectsPlan } from './reactive-effects.ts'
 
 export interface BranchPlainLoopPlan {
+  /**
+   * flatMap descriptor mode — see `PlainLoopVariant.flatMapLeafItem`
+   * (plan/loop.ts): `arrayExpr` already flattens through the descriptor
+   * body and the stringifier emits the build-or-patch renderItem.
+   */
+  flatMapLeafItem?: boolean
   kind: 'plain'
   /** See LoopPlanCommon.rowConstruction — required on every variant. */
   rowConstruction: 'string-template' | 'dom-ops'
@@ -78,6 +84,11 @@ export interface BranchPlainLoopPlan {
    * Undefined off → byte-identical (SR8).
    */
   profileLoopId?: string
+  /**
+   * Preamble-patched regions (#2389) — non-empty forces the multi-line
+   * renderItem layout, mirroring the top-level plain plan.
+   */
+  preambleRegions: readonly PreambleRegionPlan[]
 }
 
 export interface BranchCompositeLoopPlan {

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

@@ -15,7 +15,7 @@ import { buildChainedArrayExpr, varSlotId, wrapLoopParamAsAccessor } from '../..
 import { buildBranchCompositePlan } from './build-composite-loop.ts'
 import { buildBranchLoopDelegationPlan } from './build-event-delegation.ts'
 import { buildReactiveEffectsPlan } from './build-reactive-effects.ts'
-import { destructureLoopParam, loopKeyFn, buildChildRefBindings } from '../shared.ts'
+import { destructureLoopParam, loopKeyFn, buildChildRefBindings, buildPreambleRegionPlans } from '../shared.ts'
 import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
   BranchCompositeLoopPlan,
@@ -43,14 +43,21 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
     || loop.bindings.reactiveTexts.length > 0
     || loop.bindings.conditionals.length > 0
 
+  // flatMap descriptor mode — see buildPlainLoopPlan (build-loop.ts).
+  const fm = loop.flatMapClient
   const plan: BranchPlainLoopPlan = {
     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',
@@ -75,6 +82,7 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
       : 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,
   }

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

@@ -36,11 +36,18 @@ export function buildDynamicLoopDelegationPlan(
       paramBindings: elem.paramBindings,
       key: elem.key,
       index: elem.index,
+      // No loopParams spec here (unlike the row-render context) — in the
+      // delegated handler `elem.param` is bound to the plain `.find()`/
+      // indexed result, not a signal accessor, so leaf refs must stay in
+      // their literal (`t.name`) form. Passing a loopParams spec here was
+      // BUG-3: it rewrote leaf refs to accessor-call form (`t().name`),
+      // which throws since `t` is a plain object in this scope.
       mapPreamble: elem.preamble
         ? renderPreamble(elem.preamble, {
-            renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true),
+            renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true),
           })
         : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? [],
     }),
   }
 }
@@ -65,11 +72,14 @@ export function buildBranchLoopDelegationPlan(
       paramBindings: loop.paramBindings,
       key: loop.key,
       index: loop.index,
+      // See note in `buildDynamicLoopDelegationPlan` above (BUG-3): no
+      // loopParams spec — leaf refs must stay in plain-object form here.
       mapPreamble: loop.preamble
         ? renderPreamble(loop.preamble, {
-            renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
+            renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined, true),
           })
         : null,
+      mapPreambleDeclaredNames: loop.preamble?.declaredNames ?? [],
     }),
   }
 }
@@ -95,11 +105,14 @@ export function buildStaticArrayDelegationPlan(
       // array too (#1434).
       arrayExpr: buildChainedArrayExpr(elem),
       param: elem.param,
+      // See note in `buildDynamicLoopDelegationPlan` above (BUG-3): no
+      // loopParams spec — leaf refs must stay in plain-object form here.
       mapPreamble: elem.preamble
         ? renderPreamble(elem.preamble, {
-            renderLeaf: (ir) => irToHtmlTemplate(ir, 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,
     },
@@ -117,6 +130,7 @@ function buildKeyedOrIndexLookup(args: {
   key: string | null
   index: string | null
   mapPreamble: string | null
+  mapPreambleDeclaredNames: readonly string[]
 }): ItemLookup {
   const hasBindings = (args.paramBindings?.length ?? 0) > 0
   if (args.key !== null) {
@@ -132,6 +146,7 @@ function buildKeyedOrIndexLookup(args: {
       paramBindings: args.paramBindings,
       keyWithItem,
       mapPreamble: args.mapPreamble,
+      mapPreambleDeclaredNames: args.mapPreambleDeclaredNames,
       hasBindings,
       indexParam: args.index,
     }
@@ -141,6 +156,7 @@ function buildKeyedOrIndexLookup(args: {
     arrayExpr: args.array,
     param: args.param,
     mapPreamble: args.mapPreamble,
+    mapPreambleDeclaredNames: args.mapPreambleDeclaredNames,
     hasBindings,
     indexParam: args.index,
   }

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

@@ -35,6 +35,7 @@ import {
   destructureLoopParam,
   buildChildRefBindings,
   buildStaticChildRefBindings,
+  buildPreambleRegionPlans,
 } from '../shared.ts'
 import { buildLoopReactiveEffectsPlan } from './build-reactive-effects.ts'
 import { buildComponentLoopPlan } from './build-component-loop.ts'
@@ -91,6 +92,40 @@ export function buildPlainLoopPlan(elem: TopLevelLoop, profileComponentName?: st
     || elem.bindings.reactiveTexts.length > 0
     || elem.bindings.conditionals.length > 0
 
+  // flatMap descriptor mode: reconcile the FLATTENED leaves. The source
+  // accessor runs the flatMap body (plain items — per-item signals don't
+  // exist yet) producing `({ k, h })` descriptors; the keyFn reads the
+  // leaf-declared key with an index fallback. Everything row-template-
+  // related is bypassed — the stringifier emits the build-or-patch
+  // renderItem instead. Pre-fix this fell into the generic plain shape
+  // with the UN-flattened source, a null keyFn, and an EMPTY template
+  // (leaf loss at hydration; cloneNode(null) crash on adds).
+  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,
+      // flatMap loops carry no `MapCallbackPreamble` (jsx-to-ir.ts drops it
+      // for flatMapCallback), so there is nothing to patch here.
+      preambleRegions: [],
+    }
+  }
+
   return {
     kind: 'plain',
     rowConstruction: 'string-template',
@@ -116,6 +151,7 @@ export function buildPlainLoopPlan(elem: TopLevelLoop, profileComponentName?: st
     skeletonPaths: elem.skeletonPaths,
     reactiveEffects: hasReactive ? buildLoopReactiveEffectsPlan(elem, profileComponentName) : null,
     childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
+    preambleRegions: buildPreambleRegionPlans(elem.preambleRegions, elem.param, elem.paramBindings),
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,
     anchored: elem.bodyIsItemConditional ?? false,
     // Fall back to the iteration index when the loop has no key. A whole-item

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

@@ -66,8 +66,19 @@ export interface KeyedItemLookup {
    * decision.
    */
   keyWithItem: string
-  /** Optional preamble line — emitted before the handler call. */
+  /** Optional preamble line — emitted before the handler call, inside the item guard. */
   mapPreamble: string | null
+  /**
+   * `const`/`let`/function names `mapPreamble` declares (from
+   * `MapCallbackPreamble.declaredNames`). The stringifier only splices
+   * `mapPreamble` for an event whose handler text actually references one of
+   * these — a preamble that only feeds unused local state (e.g. a `cells`
+   * array builder never read by the click handler) is dead weight the
+   * delegated handler shouldn't pay for, and emitting it unconditionally is
+   * what let BUG-3's stale-context leaf render go unnoticed. Empty when
+   * `mapPreamble` is `null`.
+   */
+  mapPreambleDeclaredNames: readonly string[]
   /** True when `paramBindings` is non-empty — drives TDZ-safe lookup shape. */
   hasBindings: boolean
 }
@@ -77,6 +88,8 @@ export interface DynamicIndexItemLookup {
   arrayExpr: string
   param: string
   mapPreamble: string | null
+  /** See `KeyedItemLookup.mapPreambleDeclaredNames`. */
+  mapPreambleDeclaredNames: readonly string[]
   hasBindings: boolean
   /** Loop index param name — see `KeyedItemLookup.indexParam` (#2189). */
   indexParam: string | null
@@ -87,6 +100,8 @@ export interface StaticIndexItemLookup {
   arrayExpr: string
   param: string
   mapPreamble: string | null
+  /** See `KeyedItemLookup.mapPreambleDeclaredNames`. */
+  mapPreambleDeclaredNames: readonly string[]
   /** Loop index param name — see `KeyedItemLookup.indexParam` (#2189). */
   indexParam: string | null
   /**

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

@@ -78,6 +78,19 @@ interface DynamicLoopCommon extends LoopPlanCommon {
   paramUnwrap: string
 }
 
+/**
+ * A resolved preamble-patched region (#2389), ready to emit: `valueExpr` is
+ * already wrapped with the loop-param accessor and, for a `joinArrayChild`
+ * source, already carries the array-join ternary — the exact value
+ * `irToHtmlTemplate` computes for the same node in the row template, so a
+ * same-key update's re-patch stays byte-identical to what a fresh mount
+ * would render.
+ */
+export interface PreambleRegionPlan {
+  slotId: string
+  valueExpr: string
+}
+
 /** Per-item ref callback resolved against a child slot for emission (#1244). */
 export interface LoopChildRefBinding {
   /** bf slot ID of the target element (root or descendant of the body). */
@@ -146,6 +159,21 @@ interface PlainLoopVariant extends DynamicLoopCommon {
    * Empty when the loop has no key (only meaningful when `anchored`).
    */
   anchorKeyExpr: string
+  /**
+   * flatMap descriptor mode (`LoopCore.flatMapClient`): `arrayExpr` already
+   * includes the `.flatMap(params => descriptorBody)` projection — the
+   * runtime reconciles the FLATTENED `({ k, h })` leaves — and `keyFn` keys
+   * on `d.k` (index fallback). The stringifier emits the build-or-patch
+   * renderItem (`patchLeaf`) instead of the template-clone shape; `template`
+   * is empty and `mapPreambleWrapped` unused in this mode.
+   */
+  flatMapLeafItem?: boolean
+  /**
+   * Preamble-patched regions (#2389) — non-empty forces the multi-line
+   * renderItem layout (mirrors `childRefs`) so the region-patch effects have
+   * `__el` to query against.
+   */
+  preambleRegions: readonly PreambleRegionPlan[]
 }
 
 /**

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

@@ -20,7 +20,8 @@ import { irChildrenToJsExpr } from '../html-template.ts'
 import { emitListenerBlock } from './stringify/event-listener.ts'
 import { nameForRegistryRef } from '../component-scope.ts'
 import { BF_SCOPE, BF_HOST, BF_AT } from '@barefootjs/shared'
-import type { LoopChildRefBinding } from './plan/loop.ts'
+import type { LoopChildRefBinding, PreambleRegionPlan } from './plan/loop.ts'
+import type { PreambleRegionSource } from '../../types.ts'
 import {
   extractFreeIdentifiersFromText,
   extractFreeIdentifiersFromStatementText,
@@ -237,6 +238,30 @@ export function destructureLoopParam(
   return { head: param, unwrap: '' }
 }
 
+/**
+ * Resolve `IRLoop.preambleRegions` (#2389) into ready-to-emit
+ * `PreambleRegionPlan`s: wrap each source expression with the loop-param
+ * accessor and, for a `joinArrayChild` source, apply the same array-join
+ * ternary `irToHtmlTemplate` uses for the identical node in the row
+ * template — so the region-patch effect's re-render matches what a fresh
+ * mount would have produced. Shared by the top-level (`build-loop.ts`) and
+ * branch (`build-branch-loop.ts`) plain-loop-plan builders.
+ */
+export function buildPreambleRegionPlans(
+  regions: readonly PreambleRegionSource[] | undefined,
+  loopParam: string,
+  loopParamBindings: readonly LoopParamBinding[] | undefined,
+): readonly PreambleRegionPlan[] {
+  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 }
+  })
+}
+
 /**
  * Build a props object expression string from component prop definitions.
  * Shared by emitComponentLoopReconciliation and emitCompositeElementReconciliation.

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

@@ -14,7 +14,7 @@ import { stringifyCompositeLoop } from './composite-loop.ts'
 import { stringifyEventDelegation } from './event-delegation.ts'
 import { stringifyReactiveEffects } from './reactive-effects.ts'
 import { emitTemplateCloneInline, emitLoopItemElementSetup } from './template-parse.ts'
-import { emitLoopChildRefs } from './loop.ts'
+import { emitLoopChildRefs, emitPreambleRegionEffects } from './loop.ts'
 import type {
   BranchLoopPlan,
   BranchPlainLoopPlan,
@@ -58,6 +58,7 @@ function emitPlain(lines: string[], plan: BranchPlainLoopPlan): void {
     childRefs,
     bodyIsMultiRoot,
     profileLoopId,
+    preambleRegions,
   } = plan
 
   const loopBfId = profileLoopId ? `, ${JSON.stringify(profileLoopId)}` : ''
@@ -69,9 +70,29 @@ function emitPlain(lines: string[], plan: BranchPlainLoopPlan): void {
   // both the effect and its dependency subscriptions (observation O-2).
   lines.push(`      __disposers.push(createDisposableEffect(() => {`)
 
+  // flatMap descriptor mode — build-or-patch renderItem, mirrors the
+  // top-level shape in stringify/loop.ts (see comment there).
+  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
+  }
+
   // Non-empty `childRefs` need `__el` as a handle inside the factory body,
-  // so force the multi-line layout (#1244).
-  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0) {
+  // so force the multi-line layout (#1244) — preamble-patched regions
+  // (#2389) need the same handle for their own effect.
+  if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0 && preambleRegions.length === 0) {
     // Simple case: single-line renderItem (single root, no reactive effects).
     const cloneExpr = emitTemplateCloneInline(template)
     if (mapPreambleWrapped) {
@@ -98,6 +119,7 @@ function emitPlain(lines: string[], plan: BranchPlainLoopPlan): void {
       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})`)
   }