@barefootjs/jsx 0.26.3 → 0.27.0

package/src/ir-to-client-js/client-only-elision.ts

@@ -0,0 +1,273 @@
+/**
+ * Slot unification Step B (`spec/slot-unification.md` §3(b), §5 "Step B —
+ * marker elision"): decide, EXACTLY ONCE and BEFORE either `adapter.generate`
+ * (SSR) or `generateClientJs` (CSR) run, which `/* @client *\/` text slots
+ * can drop their `<!--bf:sN-->…<!--/-->` marker pair entirely from both
+ * outputs. Every consumer (all nine SSR adapters' `renderExpression`, and
+ * the CSR emitters in `html-template.ts`) reads the single
+ * `IRExpression.markerless` flag this pass writes — nobody re-derives the
+ * decision, per CLAUDE.md's "Never add compiler options/hooks for
+ * tool-specific output rewriting" spirit: one door in, everyone reads it.
+ *
+ * Scope — deliberately the NARROWEST slice of §3(b)'s elision rule that is
+ * fully sound today, not the general case:
+ *
+ *   Only `expr.clientOnly && expr.slotId` expressions OUTSIDE any loop or
+ *   conditional branch (i.e. reachable from the component's own render tree
+ *   by walking only `element`/`text`/`expression`/`fragment` nodes).
+ *
+ * Why THIS slice and not ordinary reactive text slots (loop rows,
+ * conditional branches): every other kind of slot's SSR-rendered width is
+ * DATA-DEPENDENT — an ordinary `{item.name}` may render empty or non-empty
+ * per request, so a LATER sibling's absolute child-index path would only be
+ * valid for the specific width THIS request happened to produce, not for
+ * every request the compiled function ever serves. `/* @client *\/`
+ * expressions are the one case free of that problem: SSR can never evaluate
+ * client-only JS (the whole point of the escape valve), so its rendered
+ * width is deterministically ZERO on every request, for every adapter, with
+ * no data dependence at all. That determinism is what makes computing a
+ * real, reusable, hydration-safe path sound here without also solving the
+ * general "does an earlier sibling's width vary by request" problem.
+ *
+ * Path safety within that scope — the part that generalizes A3's
+ * `computeSkeletonSlotPaths` (`html-template.ts`) rather than reinventing
+ * it: paths are root-relative child-index chains, exactly like that
+ * function's, walked in document order with the SAME "once we hit something
+ * whose contributed width isn't a compile-time constant, every remaining
+ * sibling AND everything nested inside it loses eligibility" rule (nested
+ * content reached only through an uncertain-index sibling would resolve an
+ * absolute path through that uncertain index — silently wrong, not loud, so
+ * it must never be attempted). Concretely, walking a children list left to
+ * right:
+ *   - a static `element` always contributes exactly one node — recurse into
+ *     its own children as an independent, freshly-indexed scope (its own
+ *     internal accounting can't leak out, and nothing external can poison
+ *     it either, since the element itself is a fixed anchor regardless of
+ *     what's inside it);
+ *   - static `text` contributes a node per HTML-parser text-run-merging
+ *     rules (adjacent text/expression children collapse into ONE Text
+ *     node — mirrors `computeSkeletonSlotPaths`'s `pendingText` tracking);
+ *   - a `clientOnly` expression with a slotId is the one ELIGIBLE case,
+ *     PROVIDED it is not itself part of a merged text run (rule (i) — the
+ *     `/* @client *\/` slot must not be immediately adjacent, once markers
+ *     are gone, to loose text or another expression, or the HTML parser
+ *     would merge them into one Text node with no way to tell which
+ *     content is which). Once one is elided, this level (and everything
+ *     nested inside any later sibling) is marked ineligible for the
+ *     remainder of the walk at this level — see the "freeze" note below;
+ *   - any other `expression` (a real reactive/static text or markup slot),
+ *     any `conditional`/`loop`/`component`/`async`/`provider`/
+ *     `if-statement`/`slot` node, is data-dependent or opaque width and
+ *     FREEZES the rest of this children list (see below) — this is
+ *     strictly conservative: it also means a `/* @client *\/` expression
+ *     is never eligible once any of these appears earlier at the same
+ *     level, even though `/* @client *\/`'s own width is always zero,
+ *     because SIBLINGS reached only via nested recursion past that point
+ *     would otherwise resolve an absolute path through the frozen node's
+ *     uncertain contributed width;
+ *   - the same hazard-tag / force-close-group / void-element / `<tr>`
+ *     foster-parenting guards `computeSkeletonSlotPaths` uses (imported,
+ *     not re-derived) abort the ENTIRE walk (a global bail, exactly like
+ *     that function's `state.bailed`) — a parser hazard means every index
+ *     computed anywhere in this tree is suspect, not just the ones near
+ *     the hazard, so "don't guess" means don't guess about the blast
+ *     radius either.
+ *
+ * "Freeze" (the one simplification versus a maximally-precise per-branch
+ * eligibility tracker): once ANY `/* @client *\/` slot at a given level is
+ * elided — OR once anything data-dependent/opaque is seen at that level —
+ * that level's remaining siblings (and anything nested only through them)
+ * stop being assigned real paths for the rest of THIS walk, even though a
+ * maximally precise analysis could sometimes still find one. This caps
+ * elision at (at most) one `/* @client *\/` slot per static subtree —
+ * conservative by design, matching the elision rule's own framing, and it
+ * guarantees two elided slots can never end up needing an insertion whose
+ * reference node depends on the other's still-unresolved width. Freezing is
+ * PER CHILDREN-LIST (an element's own children start a fresh, unfrozen
+ * scope) — global-bail is reserved for hazard tags alone.
+ *
+ * Deferred (loudly, not silently): ordinary reactive text slots in loop
+ * rows / conditional branches keep their markers — see above for why
+ * widening this to data-dependent-width content needs a materially
+ * different (and per-adapter-verified) safety argument that this PR does
+ * not attempt.
+ */
+
+import type { IRNode, IRExpression } from '../types.ts'
+import {
+  VOID_ELEMENTS,
+  SKELETON_PATH_HAZARD_TAGS,
+  skeletonForceCloseGroup,
+  hasForeignTableRowContent,
+  flattenSkeletonChildren,
+} from './html-template.ts'
+
+/** Global bail, mirroring `computeSkeletonSlotPaths`'s `state.bailed`: once
+ *  a parser hazard is seen anywhere, every remaining step of this ONE
+ *  `decideClientOnlyElision` call becomes a no-op. Slots already elided
+ *  before the hazard was reached keep their `markerless`/`elidedPath` —
+ *  those paths were computed from safe ground and remain valid; only
+ *  FURTHER assignment stops. */
+interface ElisionState {
+  bailed: boolean
+}
+
+/**
+ * Entry point: mutates `root`'s `expression` nodes in place, setting
+ * `markerless`/`elidedPath` on every eligible `/* @client *\/` slot found.
+ * Safe to call on any component's render tree; a tree with none simply
+ * mutates nothing.
+ */
+export function decideClientOnlyElision(root: IRNode): void {
+  walkNode(root, [], new Set(), { bailed: false })
+}
+
+/** Walk one node that occupies a known position (`path`) in its parent's
+ *  children. Only `element`/`fragment` are ever recursed into by the
+ *  children-list walker below — this wrapper exists so both the top-level
+ *  call and `walkChildren`'s per-element recursion can share one path. */
+function walkNode(
+  node: IRNode,
+  path: readonly number[],
+  forceCloseAncestors: ReadonlySet<number>,
+  state: ElisionState,
+): void {
+  if (state.bailed) return
+  if (node.type === 'element') {
+    if (!elementIsPathSafe(node.tag, flattenSkeletonChildren(node.children))) {
+      state.bailed = true
+      return
+    }
+    const groupIdx = skeletonForceCloseGroup(node.tag)
+    if (groupIdx >= 0 && forceCloseAncestors.has(groupIdx)) {
+      state.bailed = true
+      return
+    }
+    const nextAncestors = groupIdx >= 0 ? new Set([...forceCloseAncestors, groupIdx]) : forceCloseAncestors
+    walkChildren(flattenSkeletonChildren(node.children), path, nextAncestors, state)
+  } else if (node.type === 'fragment') {
+    walkChildren(flattenSkeletonChildren(node.children), path, forceCloseAncestors, state)
+  }
+  // Any other root shape (a bare conditional/loop/component return, etc.)
+  // has no static children list to walk — nothing to do.
+}
+
+/**
+ * Walk one parent's (already-fragment-flattened) children left to right,
+ * assigning paths to eligible `/* @client *\/` slots. `parentPath` is the
+ * path to the PARENT of this children list (the element/root whose
+ * `childNodes` these indices are relative to). `forceCloseAncestors`
+ * mirrors `computeSkeletonSlotPaths`'s ancestor-threaded force-close-group
+ * tracking (`<h2>` inside an open `<h1>`, `<li>` inside an open `<li>`, …) —
+ * threaded down through element recursion, exactly like that function.
+ * `frozen` is local to THIS call (this one children list) — an element's
+ * own children get a fresh, unfrozen scope regardless of what froze here.
+ */
+function walkChildren(
+  children: readonly IRNode[],
+  parentPath: readonly number[],
+  forceCloseAncestors: ReadonlySet<number>,
+  state: ElisionState,
+): void {
+  let frozen = false
+  let idx = 0
+  let pendingText = false
+
+  for (let i = 0; i < children.length; i++) {
+    if (state.bailed) return
+    const child = children[i]
+
+    switch (child.type) {
+      case 'text': {
+        if (child.value === '') continue
+        if (!pendingText) idx += 1
+        pendingText = true
+        continue
+      }
+
+      case 'expression': {
+        if (child.expr === 'null' || child.expr === 'undefined') continue
+        if (child.clientOnly && child.slotId) {
+          const adjacent = isTextLike(children[i - 1]) || isTextLike(children[i + 1])
+          if (!frozen && !adjacent) {
+            markElided(child, [...parentPath, idx])
+            frozen = true // one elision per level — see module docstring
+          } else {
+            frozen = true // still freeze: an un-elided expression here is
+            // no different from any other data-dependent-width sibling.
+          }
+          idx += 1
+          pendingText = false
+          continue
+        }
+        // Any other expression — data-dependent width. Freeze the rest of
+        // this level; still consume ONE index (best-effort bookkeeping —
+        // nothing downstream reads `idx` past this point since `frozen`
+        // blocks any further assignment).
+        frozen = true
+        idx += 1
+        pendingText = false
+        continue
+      }
+
+      case 'element': {
+        if (!elementIsPathSafe(child.tag, flattenSkeletonChildren(child.children))) {
+          // Hazard shape: bail the WHOLE walk (matches
+          // `computeSkeletonSlotPaths`'s "don't guess" stance), not just
+          // this level — a parser hazard means indices anywhere in this
+          // tree are untrustworthy, not only the ones near it.
+          state.bailed = true
+          return
+        }
+        if (!frozen) {
+          walkNode(child, [...parentPath, idx], forceCloseAncestors, state)
+        }
+        idx += 1
+        pendingText = false
+        continue
+      }
+
+      case 'fragment':
+        continue // already flattened
+
+      default:
+        // conditional / loop / component / async / provider / if-statement /
+        // slot: opaque or variable width. Freeze the rest of this level.
+        frozen = true
+        idx += 1
+        pendingText = false
+        continue
+    }
+  }
+}
+
+/** True for a node that would merge (per HTML text-node-merging rules) with
+ *  an adjacent bare-text-position slot if that slot's markers were removed —
+ *  rule (i) of §3(b). `undefined` (no sibling — start/end of the children
+ *  list) is never adjacent. */
+function isTextLike(node: IRNode | undefined): boolean {
+  if (!node) return false
+  if (node.type === 'text') return node.value !== ''
+  if (node.type === 'expression') return node.expr !== 'null' && node.expr !== 'undefined'
+  return false
+}
+
+function markElided(expr: IRExpression, path: readonly number[]): void {
+  expr.markerless = true
+  expr.elidedPath = path
+}
+
+/**
+ * Mirrors `computeSkeletonSlotPaths`'s per-element safety checks (hazard
+ * tags, void elements, `<tr>` foster-parenting) without re-deriving the
+ * underlying tag sets — imported from `html-template.ts` so the two walks
+ * can never silently diverge on which shapes are hazardous. Force-close
+ * groups are checked separately by the caller (`walkNode`), which has the
+ * ancestor set this check does not.
+ */
+function elementIsPathSafe(tag: string, flatChildren: readonly IRNode[]): boolean {
+  if (SKELETON_PATH_HAZARD_TAGS.has(tag)) return false
+  if (VOID_ELEMENTS.has(tag) && flatChildren.length > 0) return false
+  if (tag === 'tr' && hasForeignTableRowContent(flatChildren)) return false
+  return true
+}

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'
@@ -414,8 +414,8 @@ export function collectInnerLoops(
 
 /**
  * Decide whether a loop's runtime rendering needs element reconciliation
- * (reconcileElements + composite item rendering) rather than the simple
- * template-per-item path, and collect inner-loop metadata for its body.
+ * (mapArray/mapArrayAnchored + composite item rendering) rather than the
+ * simple template-per-item path, and collect inner-loop metadata for its body.
  *
  * Used by both the top-level `case 'loop'` in `collectElements` and the
  * branch-loop collector in `collectBranchLoops`. Each call site applies
@@ -595,7 +595,11 @@ export function collectElements(
     },
     expression: ({ node: ex, scope: inCond }) => {
       if (ex.clientOnly && ex.slotId) {
-        ctx.clientOnlyElements.push({ slotId: ex.slotId, expression: ex.expr })
+        ctx.clientOnlyElements.push({
+          slotId: ex.slotId,
+          expression: ex.expr,
+          elidedPath: ex.markerless ? ex.elidedPath : undefined,
+        })
         return
       }
       if (!ex.slotId || inCond) return
@@ -650,10 +654,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 +688,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 +713,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 +799,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,18 +1105,28 @@ 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
+      // Use loopDepth=0: this loop gets its own mapArray/mapArrayAnchored call (independent
       // from the conditional's template), so items use data-key (not data-key-1).
       // Pass loopParams so expressions reference the per-item signal accessor,
       // keeping the template consistent with reactive effect expressions that
       // 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 +1138,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 +1158,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 +1173,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