@barefootjs/jsx 0.26.2 → 0.26.4

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

@@ -60,6 +60,10 @@ export function buildComponentLoopPlan(elem: TopLevelLoop, profileComponentName?
 
   return {
     kind: 'component',
+    // Rows are createComponent-driven: a lowered HTML-string leaf passed as a
+    // prop would diverge from SSR (which passes real JSX elements). The plan
+    // dispatcher refuses a JSX-bearing preamble on this variant.
+    rowConstruction: 'dom-ops',
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     arrayExpr: buildChainedArrayExpr(elem),

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

@@ -23,6 +23,7 @@ import {
 } from '../shared.ts'
 import { buildReactiveEffectsPlan } from './build-reactive-effects.ts'
 import { buildInnerLoopsPlan } from './build-inner-loop.ts'
+import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type { CompositeLoopPlan } from './types.ts'
 
 /** @internal — prefer `buildLoopPlan`. */
@@ -36,6 +37,7 @@ export function buildTopLevelCompositePlan(elem: TopLevelLoop, profileComponentN
 
   return {
     kind: 'composite',
+    rowConstruction: 'string-template',
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     arrayExpr: buildChainedArrayExpr(elem),
@@ -43,7 +45,12 @@ export function buildTopLevelCompositePlan(elem: TopLevelLoop, profileComponentN
     paramHead,
     paramUnwrap,
     indexParam: elem.index || '__idx',
-    mapPreambleWrapped: elem.mapPreamble ? wrap(elem.mapPreamble) : '',
+    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,
     outerComps: filterCondCompsOut(outerCompsByDepth, elem.bindings.conditionals),
     outerEvents: elem.bindings.events.filter(ev => ev.nestedLoops.length === 0),
@@ -87,6 +94,7 @@ export function buildBranchCompositePlan(loop: BranchLoop, cv: string, profileCo
 
   return {
     kind: 'composite',
+    rowConstruction: 'string-template',
     containerVar: `__loop_${cv}`,
     markerId: loop.markerId,
     // Chain `.filter()` / `.toSorted()` onto the source array so the mapArray
@@ -97,7 +105,12 @@ export function buildBranchCompositePlan(loop: BranchLoop, cv: string, profileCo
     paramHead,
     paramUnwrap,
     indexParam: loop.index || '__idx',
-    mapPreambleWrapped: loop.mapPreamble ? wrap(loop.mapPreamble) : '',
+    mapPreambleWrapped: loop.preamble
+      ? renderPreamble(loop.preamble, {
+          transformJs: wrap,
+          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
+        })
+      : '',
     template: loop.template,
     outerComps: filterCondCompsOut(outerCompsByDepth, loop.bindings.conditionals),
     outerEvents: childEvents.filter(ev => ev.nestedLoops.length === 0),

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

@@ -11,6 +11,7 @@
 
 import type { TopLevelLoop, BranchLoop, LoopChildEvent } from '../../types.ts'
 import { buildChainedArrayExpr, varSlotId, substituteLoopBindings } from '../../utils.ts'
+import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
   EventDelegationPlan,
   ItemLookup,
@@ -35,7 +36,18 @@ export function buildDynamicLoopDelegationPlan(
       paramBindings: elem.paramBindings,
       key: elem.key,
       index: elem.index,
-      mapPreamble: elem.mapPreamble ?? null,
+      // 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, undefined, undefined, true),
+          })
+        : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? [],
     }),
   }
 }
@@ -60,7 +72,14 @@ export function buildBranchLoopDelegationPlan(
       paramBindings: loop.paramBindings,
       key: loop.key,
       index: loop.index,
-      mapPreamble: loop.mapPreamble ?? null,
+      // 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, undefined, undefined, true),
+          })
+        : null,
+      mapPreambleDeclaredNames: loop.preamble?.declaredNames ?? [],
     }),
   }
 }
@@ -86,7 +105,14 @@ export function buildStaticArrayDelegationPlan(
       // array too (#1434).
       arrayExpr: buildChainedArrayExpr(elem),
       param: elem.param,
-      mapPreamble: elem.mapPreamble ?? null,
+      // 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, undefined, undefined, true),
+          })
+        : null,
+      mapPreambleDeclaredNames: elem.preamble?.declaredNames ?? [],
       offset: elem.offset ?? null,
       indexParam: elem.index ?? null,
     },
@@ -104,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) {
@@ -119,6 +146,7 @@ function buildKeyedOrIndexLookup(args: {
       paramBindings: args.paramBindings,
       keyWithItem,
       mapPreamble: args.mapPreamble,
+      mapPreambleDeclaredNames: args.mapPreambleDeclaredNames,
       hasBindings,
       indexParam: args.index,
     }
@@ -128,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-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

@@ -35,10 +35,12 @@ import {
   destructureLoopParam,
   buildChildRefBindings,
   buildStaticChildRefBindings,
+  buildPreambleRegionPlans,
 } from '../shared.ts'
 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,
@@ -90,8 +92,43 @@ 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',
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${elem.slotId}` : undefined,
@@ -100,12 +137,21 @@ 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,
     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
@@ -139,6 +185,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 +235,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/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

@@ -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. */
@@ -66,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). */
@@ -134,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

@@ -14,12 +14,14 @@
 
 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'
 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,
@@ -83,7 +85,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
@@ -236,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})`)
   }