@barefootjs/jsx 0.26.1 → 0.26.3

package/src/adapters/test-adapter.ts

@@ -253,6 +253,16 @@ export class TestAdapter extends JsxAdapter {
     // parsed as a block statement (matches hono-adapter behavior).
     const safeChildren = children.startsWith('{') ? `<>${children}</>` : children
 
+    // A `.map()` callback preamble (a Stage-2 value-only `const`, or a Stage-3
+    // arbitrary array-builder) runs verbatim in the block body. Use the typed
+    // carrier so raw JSX leaves stay intact for the JSX runtime; `{out}`-style
+    // element-array children render natively. (Without this the preamble was
+    // dropped and its identifiers rendered unbound.)
+    const preamble = loop.preamble?.ssrText
+    if (preamble) {
+      return `{${loop.array}.map((${loop.param}${indexParam}) => { ${preamble} return ${safeChildren} })}`
+    }
+
     return `{${loop.array}.map((${loop.param}${indexParam}) => ${safeChildren})}`
   }
 

package/src/analyzer-context.ts

@@ -25,6 +25,7 @@ import type {
   DeclinedReactiveFactory,
 } from './types.ts'
 import { type ExcludeRange, collectAllTypeRanges, reconstructWithoutTypes } from './strip-types.ts'
+import type { CallbackBodyAcceptor } from './adapters/interface.ts'
 
 /**
  * Deferred info for BF043 (props destructuring warning).
@@ -199,6 +200,15 @@ export interface AnalyzerContext {
 
   // Errors
   errors: CompilerError[]
+  /**
+   * Capability of the adapter this component is being compiled for: can its
+   * runtime render an off-subset callback body (`filter`/`sort`/… predicate)
+   * verbatim? Set from `TemplateAdapter.acceptsCallbackBody`; undefined for
+   * direct analyzer callers (no adapter) and DSL adapters. Consulted at the
+   * Phase-1 callback-lowering sites so a JS-runtime target isn't rejected for
+   * a body it could run. See `spec/callback-fidelity.md`.
+   */
+  acceptsCallbackBody?: CallbackBodyAcceptor
 
   // Directive
   hasUseClientDirective: boolean
@@ -232,11 +242,13 @@ export interface AnalyzerContext {
 
 export function createAnalyzerContext(
   sourceFile: ts.SourceFile,
-  filePath: string
+  filePath: string,
+  acceptsCallbackBody?: CallbackBodyAcceptor
 ): AnalyzerContext {
   return {
     sourceFile,
     filePath,
+    acceptsCallbackBody,
 
     componentName: null,
     componentNode: null,
@@ -300,6 +312,22 @@ export function createAnalyzerContext(
       } catch {
         ownSourceFile = undefined
       }
+      // Test-gated trust-boundary assertion (write-side string rule,
+      // CLAUDE.md): getJS output is spliced into emitted artifacts, so a
+      // JSX-bearing node here is a leak by construction — mixed content must
+      // travel as structured segments, never as raw text. Every getJS call
+      // site shares this contract; the env gate keeps the subtree walk off
+      // the production hot path (the trichotomy harness enables it). Scoped
+      // to error-free compiles: a compile that already refused loudly may
+      // take degraded fallback paths whose artifacts are gated by the error —
+      // the invariant this trips on is the SILENT leak.
+      if (process.env.BF_ASSERT_NO_JSX_IN_GETJS === '1' && this.errors.length === 0 && nodeContainsJsx(node)) {
+        throw new Error(
+          'getJS() called on a JSX-bearing node — raw JSX must never be spliced ' +
+          'into emitted output. Carry mixed content as structured segments ' +
+          '(MapCallbackPreamble / FlatMapCallback) instead.'
+        )
+      }
       if (ownSourceFile && ownSourceFile !== sourceFile) {
         return node.getText(ownSourceFile)
       }
@@ -308,6 +336,12 @@ export function createAnalyzerContext(
   }
 }
 
+/** Subtree JSX check for the test-gated getJS assertion above. */
+function nodeContainsJsx(node: ts.Node): boolean {
+  if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) return true
+  return ts.forEachChild(node, nodeContainsJsx) ?? false
+}
+
 // =============================================================================
 // Source Location Helper
 // =============================================================================

package/src/analyzer.ts

@@ -9,6 +9,7 @@
 import ts from 'typescript'
 import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, FactoryRenameSite, SourceLocation } from './types.ts'
 import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr } from './expression-parser.ts'
+import type { CallbackBodyAcceptor } from './adapters/interface.ts'
 import { rewriteBarePropRefs } from './prop-rewrite.ts'
 import { incrementCounter } from './instrumentation.ts'
 import {
@@ -158,7 +159,8 @@ export function analyzeComponent(
   source: string,
   filePath: string,
   targetComponentName?: string,
-  program?: ts.Program
+  program?: ts.Program,
+  acceptsCallbackBody?: CallbackBodyAcceptor
 ): AnalyzerContext {
   incrementCounter('filesAnalyzed')
   // Track whether the caller supplied a shared ts.Program. Used downstream
@@ -229,7 +231,7 @@ export function analyzeComponent(
     }
   }
 
-  const ctx = createAnalyzerContext(sourceFile, filePath)
+  const ctx = createAnalyzerContext(sourceFile, filePath, acceptsCallbackBody)
   ctx.checker = checker
 
   // Reactive-factory prescan results (#931, #2325 cross-file + object-
@@ -2077,18 +2079,77 @@ function extractSingleJsxReturn(
   return jsxReturn
 }
 
-type JsxReturnNode = ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment
+export type JsxReturnNode = ts.JsxElement | ts.JsxSelfClosingElement | ts.JsxFragment
+
+/**
+ * The branch structure extracted from a multi-return JSX body — an if/else-if
+ * chain or a `switch`. Shared by the helper-function fold and (Stage 2 of
+ * `spec/callback-fidelity.md`) the `.map()` callback-body fold.
+ */
+export interface MultiReturnJsxBranches {
+  branches: Array<{
+    condition: ts.Expression
+    jsxReturn: JsxReturnNode | null
+    /**
+     * For a `switch` with fallthrough (`case 'a': case 'b': return X`), the
+     * additional case expressions that share this branch's return. The fold
+     * OR-joins them with `condition` into `disc === a || disc === b`. Only set
+     * on switch-sourced branches.
+     */
+    extraCaseConditions?: ts.Expression[]
+  }>
+  fallback: JsxReturnNode | null
+  switchDiscriminant?: ts.Expression
+  /**
+   * Leading `const` / `let` declarations before the branches, collected only
+   * when the caller passes `allowPreamble` (the `.map()` body fold — Stage 2 of
+   * `spec/callback-fidelity.md`). A JS-runtime adapter folds them into a
+   * per-iteration preamble; a DSL adapter can't carry a loop-local into a
+   * conditional branch template, so the `.map()` lowering refuses (BF021 +
+   * `/* @client *\/`) rather than render wrong output. Empty for the
+   * helper-function inliner, which passes no `allowPreamble` and still bails on
+   * any variable statement.
+   */
+  preamble?: ts.VariableStatement[]
+}
+
+/**
+ * A leading-`const` preamble is only safe to fold when every branch (and the
+ * fallback) returns real JSX. If any returns `null`, the loop item can be null
+ * and the compiler routes the loop through the anchored conditional-item
+ * runtime (`mapArrayAnchored`), where a preamble local computed before the
+ * conditional interacts badly with the per-item hydration anchor — observed as
+ * a keyed-reactivity break on a real component (the pivot-table demo, whose
+ * `.map()` body is `const f = …; if (!f) return null; return <div key={fid}>`
+ * and which carries a workaround note about exactly this compiler behavior).
+ * When unsafe, bail so the body falls through to the single-return path
+ * unchanged. Stage 2 of `spec/callback-fidelity.md`.
+ */
+function preambleUnsafe(
+  preamble: ts.VariableStatement[],
+  branches: Array<{ jsxReturn: JsxReturnNode | null }>,
+  fallback: JsxReturnNode | null,
+): boolean {
+  if (preamble.length === 0) return false
+  return fallback === null || branches.some(b => b.jsxReturn === null)
+}
 
 /**
  * Extract conditional branches from a multi-return JSX helper function body.
  * Supports if/else if chains and switch statements where every branch
  * returns JSX or null. Returns null for unsupported patterns.
  */
-function extractMultiReturnJsxBranches(
-  body: ts.Block
-): { branches: Array<{ condition: ts.Expression; jsxReturn: JsxReturnNode | null }>; fallback: JsxReturnNode | null; switchDiscriminant?: ts.Expression } | null {
-  const branches: Array<{ condition: ts.Expression; jsxReturn: JsxReturnNode | null }> = []
+export function extractMultiReturnJsxBranches(
+  body: ts.Block,
+  allowPreamble = false,
+): MultiReturnJsxBranches | null {
+  const branches: Array<{
+    condition: ts.Expression
+    jsxReturn: JsxReturnNode | null
+    extraCaseConditions?: ts.Expression[]
+  }> = []
   let fallback: JsxReturnNode | null = null
+  const preamble: ts.VariableStatement[] = []
 
   const stmts = body.statements
   for (let i = 0; i < stmts.length; i++) {
@@ -2125,7 +2186,8 @@ function extractMultiReturnJsxBranches(
             return null
           }
           if (branches.length === 0) return null
-          return { branches, fallback }
+          if (preambleUnsafe(preamble, branches, fallback)) return null
+          return { branches, fallback, preamble }
         }
         break
       }
@@ -2151,23 +2213,49 @@ function extractMultiReturnJsxBranches(
       const hasDefault = stmt.caseBlock.clauses.some(c => ts.isDefaultClause(c))
       if (!hasDefault) return null
 
+      // Case labels that fall through to the next clause's body — an empty
+      // `case 'a':` immediately before `case 'b': return X` — share that
+      // return. Accumulate their expressions and attach them to the branch of
+      // the clause that finally carries the body. Stage 2 of
+      // spec/callback-fidelity.md.
+      let pendingCases: ts.Expression[] = []
       for (const clause of stmt.caseBlock.clauses) {
+        if (ts.isCaseClause(clause) && clause.statements.length === 0) {
+          pendingCases.push(clause.expression)
+          continue
+        }
+
         const jsxReturn = findJsxReturnInCaseClause(clause)
         const nullReturn = findNullReturnInCaseClause(clause)
         if (!jsxReturn && !nullReturn) return null
+        // Reject clauses that carry extra statements around the return (a
+        // local `const`, an expression statement, …): folding drops them, the
+        // same branch-local-preamble gap as `isDirectReturnBlock`. A bare
+        // `break` is fine. (#2377 review.)
+        if (!caseClauseIsDirectReturn(clause)) return null
 
         if (ts.isCaseClause(clause)) {
           branches.push({
             condition: clause.expression,
             jsxReturn: jsxReturn ?? null,
+            extraCaseConditions: pendingCases.length > 0 ? pendingCases : undefined,
           })
+          pendingCases = []
         } else {
+          // `default`. A fallthrough INTO default (`case 'a': default:`) would
+          // need the accumulated cases to also hit the default body — an
+          // unusual shape; bail rather than guess.
+          if (pendingCases.length > 0) return null
           fallback = jsxReturn ?? null
         }
       }
+      // Trailing empty case labels with no following body (`case 'z':` last,
+      // no return anywhere after) — nothing to attach them to; bail.
+      if (pendingCases.length > 0) return null
 
       if (branches.length === 0) return null
-      return { branches, fallback, switchDiscriminant: stmt.expression }
+      if (preambleUnsafe(preamble, branches, fallback)) return null
+      return { branches, fallback, switchDiscriminant: stmt.expression, preamble }
     }
 
     // Trailing return <jsx> or return null — this is the fallback
@@ -2183,16 +2271,36 @@ function extractMultiReturnJsxBranches(
       continue
     }
 
-    // Reject bodies with variable declarations — locals referenced in
-    // conditions or JSX would become undefined after inlining.
-    if (ts.isVariableStatement(stmt)) return null
+    // Leading `const`/`let` before any branch — collected as a preamble when
+    // the caller allows it (the `.map()` body fold; Stage 2 of
+    // spec/callback-fidelity.md). The JS-runtime fold emits it once per
+    // iteration ahead of the conditional; a DSL target refuses (BF021 +
+    // `/* @client */`) since it can't carry the loop-local into a branch
+    // template. Without `allowPreamble`, or once branches have started, reject:
+    // the helper-function inliner has no place to emit it, and a mid-chain
+    // local referenced in a later condition/JSX would become undefined.
+    if (ts.isVariableStatement(stmt)) {
+      // Only `const` / `let` are collectable — a `var` hoists to the enclosing
+      // function scope with different (redeclaration / TDZ-free) semantics that
+      // the per-iteration preamble emit wouldn't preserve, so reject it.
+      // (#2379 review.)
+      const declFlags = stmt.declarationList.flags
+      const isConstOrLet =
+        (declFlags & ts.NodeFlags.Const) !== 0 || (declFlags & ts.NodeFlags.Let) !== 0
+      if (allowPreamble && isConstOrLet && branches.length === 0 && fallback === null) {
+        preamble.push(stmt)
+        continue
+      }
+      return null
+    }
 
     // Any other statement type → unsupported pattern
     return null
   }
 
   if (branches.length === 0) return null
-  return { branches, fallback }
+  if (preambleUnsafe(preamble, branches, fallback)) return null
+  return { branches, fallback, preamble }
 }
 
 /**
@@ -2208,18 +2316,17 @@ function isDirectReturnBlock(node: ts.Statement): boolean {
     for (const stmt of node.statements) {
       if (ts.isReturnStatement(stmt)) {
         returnCount++
-      } else if (
-        ts.isIfStatement(stmt) ||
-        ts.isSwitchStatement(stmt) ||
-        ts.isForStatement(stmt) ||
-        ts.isForOfStatement(stmt) ||
-        ts.isForInStatement(stmt) ||
-        ts.isWhileStatement(stmt) ||
-        ts.isDoStatement(stmt) ||
-        ts.isTryStatement(stmt)
-      ) {
-        return false
+        continue
       }
+      // Any non-return statement — a local `const`/`let`, an expression
+      // statement, or nested control flow (if/switch/for/while/try) — means
+      // this is not a *direct* return block. Folding it into an
+      // `IRConditional` branch would silently DROP the statement: the neutral
+      // IR has no per-branch carrier for a local, so a branch-local
+      // `const x = …; return <A>{x}</A>` renders `x` undefined (ReferenceError
+      // at SSR/hydration). Bail so the caller falls back conservatively.
+      // (#2377 review; Stage 2 of spec/callback-fidelity.md.)
+      return false
     }
     return returnCount === 1
   }
@@ -2253,6 +2360,37 @@ function findJsxReturnInCaseClause(
   return null
 }
 
+/**
+ * True when a `switch` case/default clause contains exactly one `return` and
+ * nothing else that would be dropped by the fold (a trailing `break` is
+ * allowed). Rejects clauses with a local `const`/`let`, an expression
+ * statement, or nested control flow — those have no per-branch preamble
+ * carrier in the folded `IRConditional`. (#2377 review; Stage 2 of
+ * spec/callback-fidelity.md.)
+ */
+function caseClauseIsDirectReturn(clause: ts.CaseClause | ts.DefaultClause): boolean {
+  let returnCount = 0
+  let seenReturn = false
+  for (const stmt of clause.statements) {
+    if (ts.isReturnStatement(stmt)) {
+      returnCount++
+      seenReturn = true
+      continue
+    }
+    if (ts.isBreakStatement(stmt)) {
+      // A `break` BEFORE the return makes the return unreachable — at runtime
+      // the case exits and the callback falls through to `undefined`, so
+      // folding it as if it returned JSX would render the wrong branch. Only a
+      // trailing break (after the return; dead but harmless) is allowed.
+      // (#2378 review.)
+      if (!seenReturn) return false
+      continue
+    }
+    return false
+  }
+  return returnCount === 1
+}
+
 function findNullReturnInCaseClause(
   clause: ts.CaseClause | ts.DefaultClause
 ): boolean {

package/src/compiler.ts

@@ -119,7 +119,7 @@ function compileMultipleComponents(
   const program = options.program ?? (needsTypeBasedDetection(source) ? createProgramForFile(source, filePath)?.program : undefined)
 
   for (const componentName of componentNames) {
-    const ctx = analyzeComponent(source, filePath, componentName, program)
+    const ctx = analyzeComponent(source, filePath, componentName, program, adapter.acceptsCallbackBody)
 
     if (!ctx.jsxReturn) {
       errors.push(...ctx.errors)
@@ -556,7 +556,7 @@ export function compileJSX(
   }
 
   // Single component flow
-  const ctx = analyzeComponent(compileSource, filePath, undefined, options.program)
+  const ctx = analyzeComponent(compileSource, filePath, undefined, options.program, options.adapter.acceptsCallbackBody)
 
   if (!ctx.jsxReturn) {
     errors.push(...ctx.errors)

package/src/expression-parser.ts

@@ -364,25 +364,22 @@ export interface SupportResult {
 // evaluate JS at runtime via hono/jsx) so this set only constrains
 // the template-language adapters.
 const UNSUPPORTED_METHODS = new Set([
-  // Higher-order array methods. Seven of these (`filter`, `every`,
-  // `some`, `find`, `findIndex`, `findLast`, `findLastIndex`) are
-  // intercepted as `higher-order` IR before reaching this gate.
-  // `map` is intercepted as an IRLoop when its callback returns JSX,
-  // and as a `CALLBACK_METHODS` evaluator lowering (`map_eval`, #2073)
-  // when it returns a value — it stays listed here so the fall-throughs
-  // (a bare `arr.map` reference, a function-reference callback) still
-  // refuse loudly. `reduce` / `reduceRight` stay
-  // listed here so the shapes the Tier C catalogue can't lower still
-  // refuse loudly: the `convertNode` call branch intercepts a matching
-  // `.reduce(fn, init)` / `.reduceRight(fn, init)` into the structured
-  // `array-method` + `ReduceOp` form *before* this gate (returning
-  // early), so only the unlowerable fall-throughs (a `.reduce(fn)` with
-  // no initial value, or a bare method reference) reach the gate and
-  // refuse. A 2-arg call whose reducer/init shape is off-catalogue
-  // returns an explicit `unsupported` from the call branch with a richer
-  // message. The rest stay refused — see #1448 Tier C for the design
-  // questions. `forEach` carries a tailored reason (see
-  // `UNSUPPORTED_METHOD_REASONS`).
+  // Higher-order array methods. `filter`, `every`, `some`, `find`,
+  // `findIndex`, `findLast`, `findLastIndex`, `reduce`, `reduceRight`
+  // and `flatMap` *with an arrow-callback argument* are recognized by
+  // `asCallbackMethodCall` and lower via the runtime evaluator
+  // (`serializeParsedExpr`) in the `call` arm ABOVE this gate — an
+  // off-subset callback body refuses there with a "complex callback"
+  // reason, not here. They stay listed in this set so the shapes that
+  // recognition can't catch — a BARE method reference (`arr.filter`
+  // uncalled) or a function-reference callback (no arrow) — still refuse
+  // loudly. (`reduce` / `reduceRight` are NOT folded into a structured
+  // `array-method` / `ReduceOp` form: #2018 P5 leaves them as a generic
+  // `call` whose reducer body + initial value serialize to the
+  // evaluator.) `map` is intercepted as an IRLoop when its callback
+  // returns JSX, and as a `CALLBACK_METHODS` evaluator lowering
+  // (`map_eval`, #2073) when it returns a value. `forEach` carries a
+  // tailored reason (see `UNSUPPORTED_METHOD_REASONS`).
   // `flat` is no longer here — `.flat(depth?)` lowers via the
   // `array-method` IR (structured `FlatDepth`) + `bf_flat` (Go) /
   // `bf->flat` (Mojo). `flatMap` stays listed as a fallback: the
@@ -395,6 +392,17 @@ const UNSUPPORTED_METHODS = new Set([
   // `IRLoop` upstream. See #1448.
   'filter', 'map', 'reduce', 'reduceRight', 'every', 'some',
   'forEach', 'flatMap',
+  // `fill` has no template lowering on any DSL adapter (it mutates the
+  // receiver in place and returns it — no ParsedExpr / evaluator form).
+  // Before it was listed here `isSupported` reported it "supported" and
+  // the adapters emitted a raw `.fill(...)` method call with no build
+  // diagnostic — the same silent footgun the string methods below
+  // documented before they were gated: it only surfaced as a crash at
+  // template-render time. Listing it makes the build fail loudly with
+  // BF101, pointing users at the `/* @client */` escape (a JS-runtime
+  // adapter still runs it verbatim, since those skip `isSupported`).
+  // See spec/callback-fidelity.md.
+  'fill',
   // #1448 Tier A — Array methods. Each method PR adds the lowering
   // (typically a new `array-method` variant or runtime helper) and
   // removes its row here. See packages/adapter-tests/fixtures/methods/.

package/src/ir-to-client-js/build-references.ts

@@ -35,6 +35,7 @@ import type {
   ReferenceSource,
   ReferencesGraph,
 } from '../types.ts'
+import { preambleAnalysisText } from '../types.ts'
 import type { IRVisitor as WalkerVisitor } from './walker.ts'
 import { attrValueToString } from './utils.ts'
 import type { ClientJsContext } from './types.ts'
@@ -151,7 +152,7 @@ export function buildReferencesGraph(ctx: ClientJsContext, irRoot: IRNode): Refe
     }
     if (elem.filterPredicate) addExprEdges(ROOT_SOURCE, elem.filterPredicate.raw, 'template-closure')
     if (elem.sortComparator) addExprEdges(ROOT_SOURCE, elem.sortComparator.raw, 'template-closure')
-    if (elem.mapPreamble) addExprEdges(ROOT_SOURCE, elem.mapPreamble, 'template-closure')
+    if (elem.preamble) addExprEdges(ROOT_SOURCE, preambleAnalysisText(elem.preamble), 'template-closure')
     for (const attr of elem.bindings.reactiveAttrs) {
       addExprEdges(ROOT_SOURCE, attr.expression, 'template-closure')
     }
@@ -316,7 +317,7 @@ export function buildReferencesGraph(ctx: ClientJsContext, irRoot: IRNode): Refe
       addExprEdges(ROOT_SOURCE, l.array, 'template-closure')
       if (l.filterPredicate) addExprEdges(ROOT_SOURCE, l.filterPredicate.raw, 'template-closure')
       if (l.sortComparator) addExprEdges(ROOT_SOURCE, l.sortComparator.raw, 'template-closure')
-      if (l.mapPreamble) addExprEdges(ROOT_SOURCE, l.mapPreamble, 'template-closure')
+      if (l.preamble) addExprEdges(ROOT_SOURCE, preambleAnalysisText(l.preamble), 'template-closure')
       descend()
       if (l.childComponent) walkChildComponent(l.childComponent)
       if (l.nestedComponents) {

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

@@ -393,7 +393,7 @@ export function collectInnerLoops(
           objectIteration: n.objectIteration,
           containerSlotId: scope.parentSlotId,
           template,
-          mapPreamble: n.mapPreamble,
+          preamble: n.preamble,
           refsOuterParam: refsOuter,
           childComponents,
           insideConditional: !flat && scope.insideCond ? true : undefined,
@@ -776,7 +776,7 @@ export function collectElements(
           raw: l.sortComparator.raw,
         } : undefined,
         chainOrder: l.chainOrder,
-        mapPreamble: l.mapPreamble,
+        preamble: l.preamble,
       })
       // Don't descend — loop-scoped variables are only available inside the iteration.
     },
@@ -1111,7 +1111,7 @@ function collectBranchLoops(
         objectIteration: n.objectIteration,
         template: childTemplate,
         containerSlotId: containerSlot,
-        mapPreamble: n.mapPreamble ?? null,
+        preamble: n.preamble,
         nestedComponents: useElementReconciliation ? n.nestedComponents : undefined,
         bindings: branchBindings,
         innerLoops: useElementReconciliation ? innerLoopsCollected : undefined,

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

@@ -21,6 +21,8 @@ import type { ReactiveEffectsPlan } from './reactive-effects.ts'
 
 export interface BranchPlainLoopPlan {
   kind: 'plain'
+  /** See LoopPlanCommon.rowConstruction — required on every variant. */
+  rowConstruction: 'string-template' | 'dom-ops'
   /**
    * Variable suffix for the container lookup — e.g. for slotId `s4` the
    * stringifier emits `__loop_s4` and queries via `$(__branchScope, 's4')`.

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

@@ -16,6 +16,7 @@ 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 { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
   BranchCompositeLoopPlan,
   BranchLoopPlan,
@@ -44,6 +45,7 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
 
   const plan: BranchPlainLoopPlan = {
     kind: 'plain',
+    rowConstruction: 'string-template',
     containerSlotId,
     containerVar,
     markerId: loop.markerId,
@@ -54,8 +56,11 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
     indexParam: loop.index || '__idx',
     // Wrap loop-param references to signal-accessor form so the preamble
     // matches the template literal's already-wrapped reads (#1065).
-    mapPreambleWrapped: loop.mapPreamble
-      ? wrapLoopParamAsAccessor(loop.mapPreamble, loop.param, loop.paramBindings)
+    mapPreambleWrapped: loop.preamble
+      ? renderPreamble(loop.preamble, {
+          transformJs: (t) => wrapLoopParamAsAccessor(t, loop.param, loop.paramBindings),
+          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
+        })
       : '',
     template: loop.template,
     reactiveEffects: hasReactiveEffects

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,11 @@ export function buildDynamicLoopDelegationPlan(
       paramBindings: elem.paramBindings,
       key: elem.key,
       index: elem.index,
-      mapPreamble: elem.mapPreamble ?? null,
+      mapPreamble: elem.preamble
+        ? renderPreamble(elem.preamble, {
+            renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true),
+          })
+        : null,
     }),
   }
 }
@@ -60,7 +65,11 @@ export function buildBranchLoopDelegationPlan(
       paramBindings: loop.paramBindings,
       key: loop.key,
       index: loop.index,
-      mapPreamble: loop.mapPreamble ?? null,
+      mapPreamble: loop.preamble
+        ? renderPreamble(loop.preamble, {
+            renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
+          })
+        : null,
     }),
   }
 }
@@ -86,7 +95,11 @@ export function buildStaticArrayDelegationPlan(
       // array too (#1434).
       arrayExpr: buildChainedArrayExpr(elem),
       param: elem.param,
-      mapPreamble: elem.mapPreamble ?? null,
+      mapPreamble: elem.preamble
+        ? renderPreamble(elem.preamble, {
+            renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined, true),
+          })
+        : null,
       offset: elem.offset ?? null,
       indexParam: elem.index ?? null,
     },