@barefootjs/jsx 0.26.3 → 0.27.0

package/src/jsx-to-ir.ts

@@ -28,6 +28,7 @@ import {
   type FlatMapCallback,
   type MapCallbackPreamble,
   type PreambleSegment,
+  type PreambleRegionSource,
   tsxSourceText,
   type SourceLocation,
   type TypeInfo,
@@ -3637,6 +3638,99 @@ function checkLoopKey(
  * item; multi-root bodies (e.g. `<><path/><path/></>`) need per-item
  * boundary markers and multi-root template cloning (#1212).
  */
+/**
+ * Recognize a flatMap PROJECTION body: a bare map-like call
+ * (`it.tags.map(...)` / nested `.flatMap(...)`) as the whole body — either
+ * an expression body (parenthesized or not) or a block whose ONLY statement
+ * is `return <call>`. Anything carrying additional statements does not
+ * qualify (it rides the structured-segments carrier instead). Returns the
+ * call expression to lower as the loop's nested-loop child, or null.
+ */
+function flatMapProjectionCall(body: ts.ConciseBody): ts.CallExpression | null {
+  let expr: ts.Expression | undefined
+  if (ts.isBlock(body)) {
+    const real = body.statements
+    if (real.length !== 1 || !ts.isReturnStatement(real[0]) || !real[0].expression) return null
+    expr = real[0].expression
+  } else {
+    expr = body
+  }
+  while (ts.isParenthesizedExpression(expr)) expr = expr.expression
+  if (!ts.isCallExpression(expr)) return null
+  if (!getMapLikeMethod(expr)) return null
+  // The descriptor synthesis renders the inner callback's raw params into
+  // the client accessor (`.map((tag, i) => ({ k, h }))`), which is only
+  // sound for plain-identifier params — a destructure pattern rides the
+  // segments carrier instead.
+  const cb = expr.arguments[0]
+  if (!cb || (!ts.isArrowFunction(cb) && !ts.isFunctionExpression(cb))) return null
+  for (const p of cb.parameters) {
+    if (!ts.isIdentifier(p.name)) return null
+  }
+  // The client descriptor is one element per flattened leaf, so the inner
+  // callback must produce a single element root (a JSX element, or a ternary
+  // whose branches are elements). Fragments / array literals ride the
+  // segments carrier.
+  let innerBody: ts.Node = cb.body
+  if (ts.isBlock(innerBody)) {
+    const ret = innerBody.statements.find(
+      (s): s is ts.ReturnStatement => ts.isReturnStatement(s) && s.expression != null,
+    )
+    if (innerBody.statements.length !== 1 || !ret?.expression) return null
+    innerBody = ret.expression
+  }
+  while (ts.isParenthesizedExpression(innerBody)) innerBody = innerBody.expression
+  const isElementish = (n: ts.Node): boolean => {
+    let m = n
+    while (ts.isParenthesizedExpression(m)) m = m.expression
+    if (ts.isJsxElement(m) || ts.isJsxSelfClosingElement(m)) return leafIsWirelessElement(m)
+    if (ts.isConditionalExpression(m)) return isElementish(m.whenTrue) && isElementish(m.whenFalse)
+    return false
+  }
+  if (!isElementish(innerBody)) return null
+  return expr
+}
+
+/**
+ * Syntactic pre-check that a projection leaf carries no per-element wiring —
+ * no event handlers, spreads, component tags, or nested JSX-bearing loops.
+ * Runs BEFORE the leaf is transformed (the accept/reject decision must not
+ * leave transform side effects — slot ids, collected events — behind when
+ * the shape falls back to the segments carrier, whose own transform would
+ * then double-register them).
+ */
+function leafIsWirelessElement(el: ts.JsxElement | ts.JsxSelfClosingElement): boolean {
+  let ok = true
+  const visit = (n: ts.Node): void => {
+    if (!ok) return
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+      // Only a lowercase plain identifier (or a namespaced name like
+      // `svg:path`) is an intrinsic element. A member/this tag
+      // (`<icons.Tag/>`, `<this.Tag/>`) is a component per JSX semantics
+      // regardless of case — the case test alone would let it through.
+      const tagNode = n.tagName
+      const isIntrinsic = ts.isIdentifier(tagNode)
+        ? !/^[A-Z]/.test(tagNode.text)
+        : ts.isJsxNamespacedName(tagNode)
+      if (!isIntrinsic) { ok = false; return }
+      for (const attr of n.attributes.properties) {
+        if (ts.isJsxSpreadAttribute(attr)) { ok = false; return }
+        if (ts.isJsxAttribute(attr)) {
+          const name = attr.name.getText()
+          if (/^on[A-Z]/.test(name)) { ok = false; return }
+        }
+      }
+    }
+    if (ts.isCallExpression(n) && getMapLikeMethod(n) && containsJsxInExpression(n)) {
+      ok = false
+      return
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(el)
+  return ok
+}
+
 function loopBodyIsMultiRoot(children: IRNode[]): boolean {
   const real = children.filter(
     (c) => !(c.type === 'text' && typeof c.value === 'string' && !c.value.trim())
@@ -3720,6 +3814,10 @@ function transformMapCall(
   // Capture nesting depth before we register this map's own params.
   // ctx.loopParams is populated by the *outer* map; if non-empty we are inside one.
   const isNested = ctx.loopParams.size > 0
+  // Diagnostic count at entry — the structural net at the scalar fallthrough
+  // de-dups against refusals fired DURING this call (leaf-wiring, DSL gates),
+  // never against unrelated diagnostics recorded before it.
+  const diagCountAtEntry = ctx.analyzer.errors.length
   // This loop's own depth (0 = outermost) is however many enclosing
   // loops are already active, captured before `ctx.loopDepth` below is
   // bumped for THIS loop's own descendants.
@@ -4271,14 +4369,85 @@ function transformMapCall(
       }
 
       // flatMap block body fallback: compile JSX inline when children
-      // couldn't be extracted via the standard single-return path.
-      if (method === 'flatMap' && children.length === 0) {
+      // couldn't be extracted via the standard single-return path. A pure
+      // single-`return <call>` projection is NOT taken here — it lowers to
+      // neutral IR below (nested-loop child), which DSL adapters templatize.
+      if (method === 'flatMap' && children.length === 0 && !flatMapProjectionCall(body)) {
         flatMapCallback = buildFlatMapCallback(callback, body, ctx)
       }
     } else {
       tryTransformRenderableBody(body)
     }
 
+    // flatMap PROJECTION body — the canonical `flatMap(it => it.tags.map(tag
+    // => <li key={...}/>))`, as an expression body or a single-`return` block
+    // (parenthesized or not). This is a pure nested-loop projection, so it
+    // lowers to NEUTRAL IR — an inner IRLoop as the loop's only child — which
+    // every SSR adapter can templatize (nested `{{range}}` on DSL backends),
+    // per spec/callback-fidelity.md's fidelity table ("single expr" row) and
+    // the array-literal flatMap precedent. Only bodies carrying STATEMENTS
+    // (early returns, consts) fall through to the segments carrier below and
+    // its DSL gate. The client reconciles the flattened leaves through the
+    // descriptor mapArray path, synthesized from this same neutral IR
+    // (`renderFlatMapProjectionClientBody`); the leaf `key` renders as the
+    // usual nested-loop `data-key-1` on both the SSR and client string
+    // sides, and the flattened reconciliation identity (`data-key`) is
+    // stamped by mapArray from the inner loop's `key` field.
+    if (method === 'flatMap' && children.length === 0 && !flatMapCallback) {
+      const projection = flatMapProjectionCall(body)
+      if (projection) {
+        const transformed = transformJsxExpression(projection, ctx, isClientOnly)
+        if (transformed && transformed.type === 'loop') {
+          children = [transformed]
+        }
+      }
+    }
+
+    // flatMap EXPRESSION body containing JSX in a non-projection shape —
+    // e.g. a call wrapping JSX. The block-body form already rides the
+    // structured-segments carrier in the isBlock branch above; an unbraced
+    // body is the same shape minus the braces, so route it through the same
+    // door. Without this the dispatch falls to the IRExpression scalar path,
+    // which splices the raw callback — JSX included — verbatim into the
+    // client bundle: a silent SyntaxError that kills the whole component's
+    // hydration.
+    if (method === 'flatMap' && children.length === 0 && !flatMapCallback && !ts.isBlock(body)) {
+      flatMapCallback = buildFlatMapCallback(callback, body, ctx)
+    }
+
+    // A flatMapCallback carries the WHOLE body (statements included) as
+    // structured segments — the generic statements-before-return `preamble`
+    // the block-body path may have collected above is a duplicate carrier.
+    // Worse, it isn't one: spliced into a mapArray renderItem it re-runs the
+    // body's control flow against the wrong binding shape (the audited
+    // `if (t().tags.length > maxTags) return [];` renderItem residue).
+    // The segments carrier is the single door; drop the shadow copy.
+    if (flatMapCallback) preamble = undefined
+
+    // Adapter gate (spec/callback-fidelity.md fidelity model): a flatMap body
+    // carried as structured segments runs verbatim on a JS runtime; a DSL
+    // template runtime cannot execute it at SSR — pre-gate, e.g. the Go
+    // adapter emitted `{{range …}}{{end}}` with an EMPTY body (silent
+    // divergence, the exact failure class the sound-or-loud invariant
+    // forbids). Refuse loudly with the /* @client */ escape, mirroring the
+    // const-preamble and array-builder gates above.
+    if (flatMapCallback && !isClientOnly && !(ctx.analyzer.acceptsCallbackBody?.('flatMap') ?? false)) {
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          getSourceLocation(body, ctx.sourceFile, ctx.filePath),
+          {
+            message:
+              'A .flatMap() callback body with statements or a nested projection ' +
+              'cannot be lowered to a template on this backend.',
+            suggestion: {
+              message: 'Add /* @client */ to render this loop on the client only',
+            },
+          }
+        )
+      )
+    }
+
     // Unregister loop params
     if (paramBindings) {
       for (const b of paramBindings) ctx.loopParams.delete(b.name)
@@ -4293,6 +4462,43 @@ function transformMapCall(
   // fall back to treating the entire expression as an IRExpression — unless
   // flatMap already built a compiled callback (flatMapCallback).
   if (children.length === 0 && !flatMapCallback) {
+    // Structural net (sound-or-loud, spec/callback-fidelity.md): a callback
+    // body that carries an INLINE JSX literal but produced no loop lowering
+    // must never fall through to the IRExpression scalar path — `ctx.getJS`
+    // strips types, not JSX, so the raw `<li …>` would splice verbatim into
+    // the emitted client bundle as a silent SyntaxError. Any recognizer gap
+    // for a JSX-bearing shape becomes a loud diagnostic here instead of a
+    // leak. (A JSX-helper CALL — `map(t => renderItem(t))` — carries no
+    // inline JSX literal and legitimately stays on the reactive-text path.)
+    const cb = node.arguments[0]
+    const cbBody = cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb)) ? cb.body : undefined
+    // Entry-count gate: a more specific refusal already fired for THIS call
+    // (e.g. the flatMap leaf-wiring check) — don't stack the generic message
+    // on top of it. Comparing against the count captured at entry (not
+    // `=== 0`) keeps the net armed when an unrelated diagnostic was recorded
+    // earlier in the file — a warning elsewhere must never silence the leak
+    // guard for this callback.
+    if (cbBody && containsJsxInExpression(cbBody) && ctx.analyzer.errors.length === diagCountAtEntry) {
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          getSourceLocation(cbBody, ctx.sourceFile, ctx.filePath),
+          {
+            message:
+              `A .${method}() callback that builds JSX in this shape cannot be ` +
+              'compiled — the JSX would leak verbatim into the client bundle. ' +
+              'Recognized bodies: a JSX element/fragment, a ternary or ' +
+              '&& / || / ?? expression, an array literal (flatMap), or a block ' +
+              'body whose return the compiler can lower.',
+            suggestion: {
+              message:
+                'Restructure the callback to return the JSX element directly ' +
+                '(or via a block body with a plain `return`).',
+            },
+          }
+        )
+      )
+    }
     return null
   }
 
@@ -4404,8 +4610,8 @@ function transformMapCall(
   const bodyIsMultiRoot = loopBodyIsMultiRoot(children)
 
   // Determine if array is static (prop) or dynamic (signal/memo).
-  // Static arrays don't need reconcileList — SSR elements are hydrated
-  // directly. Signal / memo arrays need reconcileList for dynamic DOM
+  // Static arrays don't need mapArray/mapArrayAnchored — SSR elements are
+  // hydrated directly. Signal / memo arrays need mapArray for dynamic DOM
   // updates.
   //
   // Solid-style wrap-by-default fallback (#943, follow-up to
@@ -4415,7 +4621,7 @@ function transformMapCall(
   // where `getItems` is an imported helper previously silent-dropped
   // into the static-render path, freezing the SSR-time list on the
   // client. Over-reconciling an array that happens to contain a pure
-  // call costs one extra `reconcileList` per loop; under-reconciling
+  // call costs one extra `mapArray` per loop; under-reconciling
   // is the silent-drop bug this closes.
   //
   // Destructured map params (`([, cfg]) => ...`, `({ a, b }) => ...`,
@@ -4441,10 +4647,22 @@ function transformMapCall(
     // already handles correctly.
     && !objectIteration
 
+  // #2389 patch-on-update — a signal-backed (non-static) loop whose body has
+  // a preamble may reference a preamble-declared local directly as a child
+  // expression (`{cells}`, `{stateLabel}`). `mapArray` reuses the same DOM
+  // node on a same-key update, re-running only the wired text/attr slots —
+  // this child has neither, so without a dedicated region-patch effect it
+  // freezes at its mount-time value. Static arrays are never recreated via
+  // signals, so there is nothing to patch; skip them entirely.
+  const preambleRegions = preamble && !isStaticArray
+    ? collectPreambleRegions(children, new Set(preamble.declaredNames), ctx)
+    : undefined
+
   // Collect nested components for both static and dynamic arrays.
   // Static arrays: needed for initChild hydration.
-  // Dynamic arrays with native root + component descendants: enables reconcileElements
-  // with composite rendering (placeholder + createComponent replacement).
+  // Dynamic arrays with native root + component descendants: enables
+  // mapArray/mapArrayAnchored with composite rendering (placeholder +
+  // createComponent replacement).
   const nestedComponents = collectNestedComponents(children).filter(c => c.name !== childComponent?.name)
 
   return {
@@ -4483,6 +4701,7 @@ function transformMapCall(
     depth,
     clientOnly: isClientOnly || undefined,
     preamble,
+    preambleRegions: preambleRegions && preambleRegions.length > 0 ? preambleRegions : undefined,
     paramType,
     indexType,
     paramBindings,
@@ -4527,15 +4746,19 @@ function containsJsx(node: ts.Node): boolean {
 }
 
 /**
- * Build a FlatMapCallback for complex flatMap block bodies (conditional
- * returns, variable-assigned JSX, etc.). Walks the callback body AST and
- * carries it as structured segments — JS text (types stripped) interleaved
- * with compiled JSX-leaf IR — never as a sentinel-bearing string (the
- * write-side rule in CLAUDE.md; same shape as the map-preamble carrier).
+ * Build a FlatMapCallback for complex flatMap bodies (conditional returns,
+ * variable-assigned JSX, etc.). Accepts a block body OR an expression body
+ * (`t => t.tags.map(tag => <li/>)`) — segment reconstruction and the SSR
+ * rawBody are position-based, so both shapes flow through identically (a
+ * block's text keeps its braces; an expression's text is a valid arrow body
+ * as-is). Walks the callback body AST and carries it as structured segments
+ * — JS text (types stripped) interleaved with compiled JSX-leaf IR — never
+ * as a sentinel-bearing string (the write-side rule in CLAUDE.md; same shape
+ * as the map-preamble carrier).
  */
 function buildFlatMapCallback(
   callback: ts.ArrowFunction | ts.FunctionExpression,
-  body: ts.Block,
+  body: ts.Block | ts.Expression,
   ctx: TransformContext,
 ): FlatMapCallback | undefined {
   if (!containsJsx(body)) return undefined
@@ -4577,6 +4800,66 @@ function buildFlatMapCallback(
     return undefined
   }
 
+  // A leaf that carries wiring the descriptor render path can't honour —
+  // an event handler, a component, a nested loop, or a spread — would be
+  // silently dead DOM on the client (the leaf renders as a keyed HTML
+  // string, patched wholesale on change, with no per-slot wiring). Refuse
+  // loudly (sound-or-loud), mirroring `preambleFragmentNeedsWiring` for map
+  // preambles — but deliberately NOT refusing reactive expressions: whole-
+  // leaf patching covers those.
+  for (const leafIr of leafIrs) {
+    // The descriptor path renders each leaf as ONE keyed element — the
+    // renderItem adopts `template.content.firstElementChild` and `patchLeaf`
+    // patches a single element root. A fragment (or any non-element) root
+    // would silently drop siblings client-side while SSR renders them all —
+    // the exact divergence class this carrier forbids. Refuse loudly.
+    if (leafIr.type !== 'element') {
+      const loc = 'loc' in leafIr && leafIr.loc
+        ? leafIr.loc
+        : getSourceLocation(body, ctx.sourceFile, ctx.filePath)
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          loc,
+          {
+            message:
+              'A JSX leaf produced by a .flatMap() callback must be a single ' +
+              'element — a fragment or non-element root cannot ride the keyed ' +
+              'descriptor path (each leaf hydrates and patches as one element).',
+            suggestion: {
+              message: 'Wrap the leaf content in a single keyed element.',
+            },
+          }
+        )
+      )
+      return undefined
+    }
+    if (flatMapLeafNeedsWiring(leafIr)) {
+      const loc = 'loc' in leafIr && leafIr.loc
+        ? leafIr.loc
+        : getSourceLocation(body, ctx.sourceFile, ctx.filePath)
+      ctx.analyzer.errors.push(
+        createError(
+          ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+          loc,
+          {
+            message:
+              'A JSX element produced by a .flatMap() callback cannot carry ' +
+              'event handlers, components, nested loops, or spreads — the ' +
+              'leaf renders as a keyed HTML string with no per-element wiring.',
+            suggestion: {
+              message:
+                'Restructure so the interactive element lives in a .map() body — ' +
+                'the descriptor path has no per-element wiring on any backend, ' +
+                'so /* @client */ does not lift this.',
+            },
+          }
+        )
+      )
+      return undefined
+    }
+  }
+
   const pieces = reconstructAsSegments(body, ctx.sourceFile, ctx.analyzer.typeExcludeRanges, leafSpans)
   const segments: PreambleSegment[] = pieces.map((piece) => {
     if ('marker' in piece) return { kind: 'jsx', ir: leafIrs[piece.marker] }
@@ -4610,6 +4893,35 @@ interface PreambleCollection {
   refusalNode?: ts.Node
 }
 
+/**
+ * Does a flatMap segment leaf carry wiring the descriptor render path can't
+ * honour? Narrower than {@link preambleFragmentNeedsWiring}: reactive
+ * expressions are ALLOWED (the client renders each leaf as a keyed
+ * `{ k, h }` descriptor and patches the whole leaf when its HTML changes),
+ * but events, components, nested loops, and spreads have no wiring on that
+ * path and would be silently dead.
+ */
+function flatMapLeafNeedsWiring(ir: IRNode): boolean {
+  switch (ir.type) {
+    case 'component':
+    case 'loop':
+      return true
+    case 'element':
+      if (ir.events.length > 0) return true
+      if (ir.attrs.some((a) => a.name.startsWith('...'))) return true
+      return ir.children.some(flatMapLeafNeedsWiring)
+    case 'conditional':
+      return (
+        flatMapLeafNeedsWiring(ir.whenTrue) ||
+        (ir.whenFalse ? flatMapLeafNeedsWiring(ir.whenFalse) : false)
+      )
+    case 'fragment':
+      return ir.children.some(flatMapLeafNeedsWiring)
+    default:
+      return false
+  }
+}
+
 /**
  * Does a compiled preamble JSX leaf carry wiring the verbatim render path can't
  * honour? The path builds each leaf once as an interpolated HTML string with no
@@ -4677,6 +4989,61 @@ function flagArrayChildExpressions(nodes: IRNode[], declared: ReadonlySet<string
   }
 }
 
+/**
+ * #2389 patch-on-update — walk loop-body children and classify each
+ * `IRExpression` whose free identifiers intersect `declared` (the enclosing
+ * `.map()` preamble's `declaredNames`) as a preamble-patched region. Unlike
+ * {@link flagArrayChildExpressions} (which only recognizes the exact bare
+ * `{out}` shape for the array-join coercion), this is deliberately broader —
+ * ANY expression reading a preamble local needs the region-patch effect,
+ * whether it's a builder array (`{cells}`, `joinArrayChild` already set by
+ * `flagArrayChildExpressions`, called earlier for the same `children`) or a
+ * plain value (`{stateLabel}`).
+ *
+ * Reuses an existing `slotId` when the node already has one (e.g. it also
+ * reads the loop param and so already qualified via the ordinary reactive-
+ * text path) rather than allocating a second slot — `node.preambleRegion`
+ * is the single source of truth downstream, so `collectLoopChildReactiveTexts`
+ * can unconditionally defer to it.
+ */
+function collectPreambleRegions(
+  nodes: IRNode[],
+  declared: ReadonlySet<string>,
+  ctx: TransformContext,
+): PreambleRegionSource[] {
+  const regions: PreambleRegionSource[] = []
+  const visit = (list: IRNode[]): void => {
+    for (const node of list) {
+      switch (node.type) {
+        case 'expression': {
+          const refs = extractFreeIdentifiersFromText(node.expr)
+          const usesPreambleLocal = [...refs].some((r) => declared.has(r))
+          if (usesPreambleLocal) {
+            if (!node.slotId) node.slotId = generateSlotId(ctx)
+            node.preambleRegion = true
+            node.reactive = true
+            regions.push({
+              slotId: node.slotId,
+              expr: node.expr,
+              joinArrayChild: node.joinArrayChild || undefined,
+            })
+          }
+          break
+        }
+        case 'element':
+        case 'fragment':
+          visit(node.children)
+          break
+        case 'conditional':
+          visit([node.whenTrue, ...(node.whenFalse ? [node.whenFalse] : [])])
+          break
+      }
+    }
+  }
+  visit(nodes)
+  return regions
+}
+
 /**
  * Collect the names a binding introduces, recursing through object/array
  * destructuring patterns (`const { id: k } = r`, `const [k, ...rest] = xs`) so
@@ -6198,7 +6565,7 @@ function isArrayExprDirectPropRef(arrayExpr: ts.Expression, ctx: TransformContex
 
 /**
  * Check if array expression is a signal or memo getter call.
- * Used to determine if a loop needs reconcileList for dynamic DOM updates.
+ * Used to determine if a loop needs mapArray for dynamic DOM updates.
  * Props and local constants are considered static (don't change at runtime).
  */
 function isSignalOrMemoArray(array: string, ctx: TransformContext): boolean {
@@ -6401,7 +6768,7 @@ function attrValueReactivityProbe(value: AttrValue): string | null {
 
 /**
  * Propagate slotId to loop children that need it.
- * Loops need to use their parent element's slotId for reconcileList.
+ * Loops need to use their parent element's slotId for mapArray.
  * This handles loops directly in children or nested in fragments.
  */
 function propagateSlotIdToLoops(children: IRNode[], slotId: string): void {

package/src/types.ts

@@ -380,6 +380,16 @@ export interface IRExpression {
    * flag (their JSX runtime renders an array child natively).
    */
   joinArrayChild?: boolean
+  /**
+   * True when this expression was classified as a loop's preamble-patched
+   * region (#2389 — see `IRLoop.preambleRegions`): its free identifiers
+   * intersect the enclosing loop's `preamble.declaredNames`. Excludes the
+   * node from `collectLoopChildReactiveTexts` (which patches via
+   * `.textContent`, wrong for markup) regardless of `reactive` / `slotId` —
+   * the region-patch effect (a claimed 'markup' slot writer, slot
+   * unification A3) is its only wiring.
+   */
+  preambleRegion?: boolean
   /** When true, expression calls signal getters or memos (has reactive `foo()` pattern). */
   callsReactiveGetters?: boolean
   /** When true, expression contains function call(s) — any `identifier()` pattern (computed from AST). */
@@ -391,6 +401,28 @@ export interface IRExpression {
    * source of truth for free-reference / reactivity classification.
    */
   origin: OriginInfo
+  /**
+   * Slot unification Step B (`spec/slot-unification.md` §3(b), §5 Step B):
+   * true when this slot's `<!--bf:sN-->…<!--/-->` marker pair can be safely
+   * omitted from BOTH SSR and CSR output, because `elidedPath` already gives
+   * every claimer a real compile-time DOM path to the slot's position.
+   * Decided EXACTLY ONCE, by `client-only-elision.ts`, before either
+   * `adapter.generate()` (SSR) or `generateClientJs()` (CSR) run — every one
+   * of the nine SSR adapters' `renderExpression` and the CSR template
+   * emitters (`html-template.ts`) read this single flag and must never
+   * re-derive their own elision decision. Unset/false is always safe
+   * (keeps markers, today's behavior); only the compiler pass above may
+   * ever set it true.
+   */
+  markerless?: boolean
+  /**
+   * Root-relative child-index path to this slot's position (parent index
+   * chain, LAST element = the index of the slot itself within its parent's
+   * `childNodes`). Valid, and required, only when `markerless` is true —
+   * see `SlotSpec.markerless` in `@barefootjs/client/runtime/claim-slots.ts`
+   * for the claim-time resolve-or-create semantics this path feeds.
+   */
+  elidedPath?: readonly number[]
 }
 
 export interface IRConditional {
@@ -702,6 +734,29 @@ export interface IRLoop {
    */
   preamble?: MapCallbackPreamble
 
+  /**
+   * Expression children of the loop body whose free identifiers intersect
+   * `preamble.declaredNames` (#2389, patch-on-update follow-up to the Stage 3
+   * root cure) — e.g. `{cells}` in `arr.map(t => { const cells = []; ...;
+   * return <tr>{cells}<td>{t.name}</td></tr> })`. `mapArray` reuses the same
+   * DOM node on a same-key item update via per-item `setItem`, re-running
+   * only the wired text/attr slots — a preamble-derived child has NEITHER
+   * (it's a bare interpolation, `joinArrayChild` array-join or otherwise),
+   * so without this it freezes at its mount-time value forever. Each entry's
+   * `slotId` is emitted as the usual `<!--bf:sN-->...<!--/-->` marker pair
+   * (same door as a reactive text slot — `irToHtmlTemplate` / Hono's
+   * `renderExpression` key off `slotId` alone), but the CLIENT wiring is a
+   * distinct claimed 'markup'-slot region-patch effect (`preambleRegions`
+   * in the client-JS loop plan), NOT a `reactiveTexts` entry — patching via
+   * `.textContent` would escape markup that a `joinArrayChild` region must
+   * render raw. `collectLoopChildReactiveTexts` excludes any node collected
+   * here (`IRExpression.preambleRegion`) so a qualifying expression is never
+   * double-wired. Populated only when `preamble` is set and the loop is NOT
+   * `isStaticArray` — a static array's SSR-rendered items are never
+   * recreated via signals, so there is nothing to patch.
+   */
+  preambleRegions?: PreambleRegionSource[]
+
   /**
    * When `.map(callback)` destructures its item parameter (array or object
    * pattern), this captures each destructured binding's name and the
@@ -809,6 +864,23 @@ export interface MapCallbackPreamble {
   builderNames: string[]
 }
 
+/**
+ * One loop-body expression child classified as a preamble-patched region
+ * (#2389 — see `IRLoop.preambleRegions`). `expr` is the raw (unwrapped)
+ * expression text, exactly as carried on the source `IRExpression` node;
+ * emitters wrap it with the loop-param accessor at codegen time, matching
+ * every other loop-body expression. `joinArrayChild` mirrors the
+ * `IRExpression` field of the same name — the client-JS plan builder uses it
+ * to decide between the array-join value expression and a plain (escaped)
+ * text value, keeping the region's re-render byte-identical to the row
+ * template's own `irToHtmlTemplate` rendering of the same node.
+ */
+export interface PreambleRegionSource {
+  slotId: string
+  expr: string
+  joinArrayChild?: boolean
+}
+
 /**
  * The preamble's JS text (js segments only, concatenated), for read-side
  * analysis — free-identifier scans, reachability edges, rest-misuse checks.