@barefootjs/jsx 0.34.0 → 0.35.1

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

@@ -7,8 +7,18 @@
  *   - Sibling levels at the same depth are flattened into the top-level
  *     list; deeper levels become `childLevels` of the immediately-preceding
  *     ancestor.
- *   - Choose `reactive` vs `static` mode by checking whether `inner.array`
- *     references the *current* outer loop param (the O-8 narrowing fix).
+ *   - Every level gets the full reactive `mapArray` emission (#2865 —
+ *     the former "static forEach, setup-only" shortcut for a nested
+ *     `.map()` whose array didn't textually mention the outer loop's item
+ *     silently froze any OTHER reactivity the inner array or its rows
+ *     depended on: a signal, a memo, a prop, an imported function call, a
+ *     preamble local, a destructured outer param, an outer-index-derived
+ *     array — none of those are "the outer item", so `refsParent` missed
+ *     all of them, and the static emitter never wired a single
+ *     `createEffect` for the row's own reactiveTexts/reactiveAttrs/
+ *     conditionals either. A `mapArray` over a genuinely non-reactive
+ *     array just subscribes to nothing and runs once — a strict superset
+ *     of what the deleted static path did).
  *   - Recurse with `inner.param` as the new outerLoopParam so deeper
  *     levels see their immediate parent.
  */
@@ -28,7 +38,7 @@ import {
   wrapLoopParamAsAccessor,
   attrValueToString,
 } from '../../utils.ts'
-import { buildChildRefBindings, buildStaticChildRefBindings } from '../shared.ts'
+import { buildChildRefBindings } from '../shared.ts'
 import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import { buildLoopChildConditionalsPlan } from './build-loop-child-arm.ts'
 import type { LoopChildConditionalPlan } from './loop-child-arm.ts'
@@ -67,7 +77,6 @@ import type {
   InnerLoopPlan,
   InnerLoopReactiveAttr,
   InnerLoopReactiveEmit,
-  InnerLoopStaticEmit,
   InnerLoopText,
   InnerLoopsPlan,
 } from './inner-loop.ts'
@@ -77,6 +86,8 @@ export interface BuildInnerLoopsArgs {
   parentElVar: string
   outerLoopParam: string | undefined
   outerLoopParamBindings?: readonly LoopParamBinding[]
+  /** Outer loop's index param name, when present (#2861). */
+  outerLoopIndex?: string | null
 }
 
 /**
@@ -85,9 +96,9 @@ export interface BuildInnerLoopsArgs {
  * conditional branch are skipped (they're emitted by `stringifyBranchInnerLoops`).
  */
 export function buildInnerLoopsPlan(args: BuildInnerLoopsArgs): InnerLoopsPlan {
-  const { levels, parentElVar, outerLoopParam, outerLoopParamBindings } = args
+  const { levels, parentElVar, outerLoopParam, outerLoopParamBindings, outerLoopIndex } = args
   const wrapOuter = outerLoopParam
-    ? (expr: string) => wrapLoopParamAsAccessor(expr, outerLoopParam, outerLoopParamBindings)
+    ? (expr: string) => wrapLoopParamAsAccessor(expr, outerLoopParam, outerLoopParamBindings, outerLoopIndex)
     : (expr: string) => expr
 
   const plan: InnerLoopPlan[] = []
@@ -111,17 +122,13 @@ export function buildInnerLoopsPlan(args: BuildInnerLoopsArgs): InnerLoopsPlan {
       ? `qsa(${parentElVar}, '[bf="${inner.containerSlotId}"]')`
       : parentElVar
 
-    // O-8 narrowing: at depth 2+, `inner.array` may reference the *immediate*
-    // parent loop's param. Check against whatever outerLoopParam our caller
-    // narrowed to — the recursion passes `inner.param` for child levels.
-    const refsParent = !!outerLoopParam && (inner.arrayFreeIdentifiers?.has(outerLoopParam) ?? false)
-    const useReactive = refsParent && !!inner.template
+    // #2865: every nested loop gets the full reactive `mapArray` emission,
+    // regardless of whether its array references the outer loop's item —
+    // see the module docstring for why the old `refsParent`-gated static
+    // shortcut was unsound.
+    const emit: InnerLoopReactiveEmit = buildReactiveEmit(inner, level, wrapOuter, uidSuffix, outerLoopParam, outerLoopParamBindings, outerLoopIndex)
 
-    const emit: InnerLoopReactiveEmit | InnerLoopStaticEmit = useReactive
-      ? buildReactiveEmit(inner, level, wrapOuter, uidSuffix, outerLoopParam, outerLoopParamBindings)
-      : buildStaticEmit(inner, level, uidSuffix)
-
-    const arrayExpr = useReactive ? wrapOuter(inner.array) : inner.array
+    const arrayExpr = wrapOuter(inner.array)
 
     const childLevelsPlan = childLevels.length > 0
       ? buildInnerLoopsPlan({
@@ -129,6 +136,7 @@ export function buildInnerLoopsPlan(args: BuildInnerLoopsArgs): InnerLoopsPlan {
           parentElVar: `__innerEl${uidSuffix}`,
           outerLoopParam: inner.param,
           outerLoopParamBindings: inner.paramBindings,
+          outerLoopIndex: inner.index,
         })
       : []
 
@@ -146,6 +154,7 @@ export function buildInnerLoopsPlan(args: BuildInnerLoopsArgs): InnerLoopsPlan {
       childLevels: childLevelsPlan,
       outerLoopParam,
       outerLoopParamBindings,
+      outerLoopIndex,
     })
 
     i = j
@@ -160,12 +169,13 @@ function buildReactiveEmit(
   uidSuffix: string,
   outerLoopParam?: string,
   outerLoopParamBindings?: readonly LoopParamBinding[],
+  outerLoopIndex?: string | null,
 ): InnerLoopReactiveEmit {
-  const wrapInner = (expr: string) => wrapLoopParamAsAccessor(expr, inner.param, inner.paramBindings)
-  const wrapBoth = (expr: string) => wrapLoopParamAsAccessor(wrapOuter(expr), inner.param, inner.paramBindings)
+  const wrapInner = (expr: string) => wrapLoopParamAsAccessor(expr, inner.param, inner.paramBindings, inner.index)
+  const wrapBoth = (expr: string) => wrapLoopParamAsAccessor(wrapOuter(expr), inner.param, inner.paramBindings, inner.index)
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(inner.param, inner.paramBindings)
   const wrappedKey = inner.key
-    ? wrapLoopParamAsAccessor(inner.key, inner.param, inner.paramBindings)
+    ? wrapLoopParamAsAccessor(inner.key, inner.param, inner.paramBindings, inner.index)
     : null
 
   // Inner-wrap children IR recursively so nested component props (e.g.,
@@ -202,12 +212,12 @@ function buildReactiveEmit(
 
   const reactiveTexts: InnerLoopText[] = inner.bindings.reactiveTexts.map(text => ({
     slotId: text.slotId,
-    wrappedExpression: wrapLoopParamAsAccessor(wrapOuter(text.expression), inner.param, inner.paramBindings),
+    wrappedExpression: wrapLoopParamAsAccessor(wrapOuter(text.expression), inner.param, inner.paramBindings, inner.index),
     insideConditional: !!text.insideConditional,
   }))
 
   const reactiveAttrs: InnerLoopReactiveAttr[] = inner.bindings.reactiveAttrs.map(attr => {
-    const wrapped = wrapLoopParamAsAccessor(wrapOuter(attr.expression), inner.param, inner.paramBindings)
+    const wrapped = wrapLoopParamAsAccessor(wrapOuter(attr.expression), inner.param, inner.paramBindings, inner.index)
     return {
       slotId: attr.childSlotId,
       attrName: attr.attrName,
@@ -240,17 +250,17 @@ function buildReactiveEmit(
     // wrapInner(wrapOuter(...)) applied to the js text.
     const leafLoopParams = outerLoopParam
       ? [
-          { param: outerLoopParam, bindings: outerLoopParamBindings },
-          { param: inner.param, bindings: inner.paramBindings },
+          { param: outerLoopParam, bindings: outerLoopParamBindings, index: outerLoopIndex },
+          { param: inner.param, bindings: inner.paramBindings, index: inner.index },
         ]
-      : [{ param: inner.param, bindings: inner.paramBindings }]
+      : [{ param: inner.param, bindings: inner.paramBindings, index: inner.index }]
     preludeStatements.push(renderPreamble(inner.preamble, {
       transformJs: (t) => wrapInner(wrapOuter(t)),
       renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, leafLoopParams, undefined),
     }))
   }
 
-  const childRefs = buildChildRefBindings(inner.bindings.refs, inner.param, inner.paramBindings)
+  const childRefs = buildChildRefBindings(inner.bindings.refs, inner.param, inner.paramBindings, inner.index)
 
   // Per-item conditionals inside THIS loop's own row (#2706) — same
   // insert()-parity treatment the top-level loop's row conditionals
@@ -265,6 +275,7 @@ function buildReactiveEmit(
     wrap: wrapBoth,
     loopParam: inner.param,
     loopParamBindings: inner.paramBindings,
+    loopIndex: inner.index,
   })
 
   return {
@@ -283,37 +294,3 @@ function buildReactiveEmit(
     childRefs,
   }
 }
-
-function buildStaticEmit(inner: NestedLoop, level: DepthLevel, uidSuffix: string): InnerLoopStaticEmit {
-  // Static `forEach` iterates with the literal item as its first param, so
-  // no signal-accessor rewrite is needed — emit the preamble verbatim
-  // before the component/event setup so prop getters and event handlers
-  // can resolve the locals (#1064). Refs follow the same contract:
-  // wrapping the callback would rewrite `s.x` to `s().x` and throw at
-  // runtime when the callback closes over the static inner param (#1244,
-  // PR #1352 Copilot review).
-  //
-  // The index alias (#2218) lands first, same rationale as the reactive
-  // path: `forEach`'s second param is the synthetic `__innerIdx<uid>`, not
-  // the user's index name, so a preamble/prop/event that reads it needs the
-  // alias bound before anything else runs.
-  const preludeStatements: string[] = []
-  const indexAlias = nestedLoopIndexAlias(inner, `__innerIdx${uidSuffix}`, inner.param, level.comps, level.events)
-  if (indexAlias) preludeStatements.push(indexAlias)
-  // Static `forEach` receives the literal item, so neither the js text nor a
-  // leaf's param reads get accessor-wrapped (mirrors the verbatim emission
-  // of the js segments above).
-  if (inner.preamble) {
-    preludeStatements.push(renderPreamble(inner.preamble, {
-      renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, undefined, undefined),
-    }))
-  }
-  return {
-    mode: 'static',
-    rawKey: inner.key ?? null,
-    preludeStatements,
-    components: level.comps,
-    events: level.events,
-    childRefs: buildStaticChildRefBindings(inner.bindings.refs),
-  }
-}

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

@@ -156,6 +156,17 @@ export interface LazyRowPlanData {
    * both parsed once per loop and clones on a flip.
    */
   conditionals: readonly LazyRowConditionalBinding[]
+  /**
+   * At least one binding, condition, or preamble-substituted dependency reads
+   * the loop's index parameter (#2859 follow-up — `ClassifiedLazyBinding.
+   * referencesIndex`, which also forces `readsItem: true` for that binding).
+   * The stringifier binds `const <indexParam> = __e.index` at the top of
+   * `applyItem` and inside `applyOuter`'s per-entry loop only when this is
+   * true, and emits `indexDriven: true` on the plan object literal so the
+   * runtime (`mapArrayLazy`) also calls `applyItem` on a pure reorder — a
+   * position change with no item change — not just an item change.
+   */
+  readsIndex: boolean
 }
 
 export interface BuildLazyRowArgs {
@@ -198,7 +209,7 @@ export function decideLazyRow(args: BuildLazyRowArgs): {
   // bodies BEFORE classifying, because a binding that reads a declared local
   // inherits the preamble's dependencies rather than its own literal names.
   const primableNames = new Set<string>([...scope.signals.keys(), ...scope.memos])
-  const preambleAnalysis = analyzeLazyPreamble(loop.preamble, args.indexParam, primableNames)
+  const preambleAnalysis = analyzeLazyPreamble(loop.preamble, primableNames)
 
   // §9.5 conditional widening: a row conditional whose arms are wiring-free
   // static elements is driven from the apply bodies instead of a per-row
@@ -207,9 +218,14 @@ export function decideLazyRow(args: BuildLazyRowArgs): {
   const condFacts: LazyConditionalFacts[] = []
   let conditionalRefusal: string | null = null
   for (const cond of rawConditionals) {
-    const verdict = analyzeLazyConditional(cond, args.indexParam, {
-      whenTrueHtml: addCondAttrToTemplate(wrap(cond.whenTrueHtml), cond.slotId),
-      whenFalseHtml: addCondAttrToTemplate(wrap(cond.whenFalseHtml), cond.slotId),
+    // whenTrueHtml/whenFalseHtml are already loop-param-wrapped at IR
+    // render time (`irToHtmlTemplate`'s `loopParams`, collect-elements.ts)
+    // — do NOT re-wrap the rendered HTML string here (#2868: a
+    // word-boundary regex over assembled markup can match a bare tag name
+    // colliding with the param/index identifier, e.g. `<i>` -> `<i()>`).
+    const verdict = analyzeLazyConditional(cond, {
+      whenTrueHtml: addCondAttrToTemplate(cond.whenTrueHtml, cond.slotId),
+      whenFalseHtml: addCondAttrToTemplate(cond.whenFalseHtml, cond.slotId),
     })
     if (!verdict.lazySafe) { conditionalRefusal = verdict.reason; break }
     condFacts.push(verdict.facts)
@@ -374,6 +390,11 @@ export function decideLazyRow(args: BuildLazyRowArgs): {
       itemNeedsPreamble: [...attrs, ...texts, ...conditionals].some(b => b.readsItem && b.readsPreamble),
       outerNeedsPreamble: [...attrs, ...texts, ...conditionals].some(b => b.readsOuter && b.readsPreamble),
       conditionals,
+      // From the RAW classification, not the final lists: a binding that
+      // reads the index is always `readsItem` (see `classifyLazyBinding`),
+      // so checking the final lists would say the same thing — raw is just
+      // the more direct source of truth.
+      readsIndex: classified.some(c => c.referencesIndex),
     },
     decision,
   }

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

@@ -202,6 +202,8 @@ export interface BuildBranchInnerLoopsArgs {
   outerLoopParam: string
   /** Outer loop param destructuring metadata. */
   outerLoopParamBindings?: readonly LoopParamBinding[]
+  /** Outer loop's index param name, when present (#2861). */
+  outerLoopIndex?: string | null
   /**
    * Outer-wrap closure — defaults to wrapping with `outerLoopParam`. Overridden
    * by `emitNestedLoopChildConditionals` recursion (which threads its own wrap).
@@ -225,6 +227,7 @@ export function buildBranchInnerLoopsPlan(
     condSlotId,
     outerLoopParam,
     outerLoopParamBindings,
+    outerLoopIndex,
     wrapOuter,
   } = args
   if (!innerLoops || innerLoops.length === 0) return []
@@ -232,10 +235,15 @@ export function buildBranchInnerLoopsPlan(
   const plan: BranchInnerLoop[] = []
   for (let i = 0; i < innerLoops.length; i++) {
     const inner = innerLoops[i]
-    if (!inner.refsOuterParam || !inner.template) continue
+    // #2865: an inner loop inside a conditional arm used to be dropped
+    // entirely (no `mapArray`, no hydration wiring at all) whenever its
+    // array didn't reference the outer loop's item — the same unsound
+    // gate `build-inner-loop.ts` used, just answered by skipping instead
+    // of falling back to a weaker static emission. Always build the plan.
+    if (!inner.template) continue
 
-    const wrapInner = (expr: string) => wrapLoopParamAsAccessor(expr, inner.param, inner.paramBindings)
-    const wrapBoth = (expr: string) => wrapLoopParamAsAccessor(wrapOuter(expr), inner.param, inner.paramBindings)
+    const wrapInner = (expr: string) => wrapLoopParamAsAccessor(expr, inner.param, inner.paramBindings, inner.index)
+    const wrapBoth = (expr: string) => wrapLoopParamAsAccessor(wrapOuter(expr), inner.param, inner.paramBindings, inner.index)
 
     const csl = inner.containerSlotId
     // Inner loop's container: host-side `bf="<slot>"` slot marker first,
@@ -251,7 +259,7 @@ export function buildBranchInnerLoopsPlan(
 
     const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(inner.param, inner.paramBindings)
     const wrappedKey = inner.key
-      ? wrapLoopParamAsAccessor(inner.key, inner.param, inner.paramBindings)
+      ? wrapLoopParamAsAccessor(inner.key, inner.param, inner.paramBindings, inner.index)
       : null
 
     // Inner-wrap children IR recursively so nested component props (e.g.
@@ -327,11 +335,13 @@ export function buildBranchInnerLoopsPlan(
         wrap: wrapBoth,
         loopParam: inner.param,
         loopParamBindings: inner.paramBindings,
+        loopIndex: inner.index,
       }),
       innerLoopParam: inner.param,
       innerLoopParamBindings: inner.paramBindings,
       outerLoopParam,
       outerLoopParamBindings,
+      outerLoopIndex,
     })
   }
   return plan
@@ -352,6 +362,8 @@ export interface BuildLoopChildConditionalsArgs {
   loopParam: string
   /** Loop param destructuring metadata. */
   loopParamBindings?: readonly LoopParamBinding[]
+  /** Loop's index param name, when it declares one (#2861) — same role as `loopParam` above. */
+  loopIndex?: string | null
 }
 
 /**
@@ -360,7 +372,8 @@ export interface BuildLoopChildConditionalsArgs {
  * recursion. Each conditional pre-builds:
  *
  *   - the wrapped condition expression
- *   - the wrapped + addCondAttr'd whenTrue / whenFalse template HTML
+ *   - the addCondAttr'd whenTrue / whenFalse template HTML (already
+ *     loop-param-wrapped at IR render time, #2868)
  *   - per-arm `LoopChildArmPlan`: events / child components / inner
  *     loops / nested conditionals (recursion)
  *
@@ -370,7 +383,7 @@ export interface BuildLoopChildConditionalsArgs {
 export function buildLoopChildConditionalsPlan(
   args: BuildLoopChildConditionalsArgs,
 ): LoopChildConditionalPlan[] {
-  const { conditionals, scopeVar, wrap, loopParam, loopParamBindings } = args
+  const { conditionals, scopeVar, wrap, loopParam, loopParamBindings, loopIndex } = args
   if (!conditionals || conditionals.length === 0) return []
 
   const plans: LoopChildConditionalPlan[] = []
@@ -379,13 +392,20 @@ export function buildLoopChildConditionalsPlan(
       slotId: cond.slotId,
       scopeVar,
       wrappedCondition: wrap(cond.condition),
-      whenTrueTemplateHtml: addCondAttrToTemplate(wrap(cond.whenTrueHtml), cond.slotId),
-      whenFalseTemplateHtml: addCondAttrToTemplate(wrap(cond.whenFalseHtml), cond.slotId),
+      // whenTrueHtml/whenFalseHtml are already loop-param-wrapped for the
+      // full ancestor chain at IR render time (`irToHtmlTemplate`'s
+      // `loopParams`, collect-elements.ts) — do NOT re-wrap the rendered
+      // HTML string here (#2868: a word-boundary regex over assembled
+      // markup can match a bare tag name colliding with the param/index
+      // identifier, e.g. `<i>` -> `<i()>`).
+      whenTrueTemplateHtml: addCondAttrToTemplate(cond.whenTrueHtml, cond.slotId),
+      whenFalseTemplateHtml: addCondAttrToTemplate(cond.whenFalseHtml, cond.slotId),
       whenTrueArm: buildLoopChildArmPlan({
         branch: cond.whenTrue,
         wrap,
         loopParam,
         loopParamBindings,
+        loopIndex,
         condId: cond.slotId,
       }),
       whenFalseArm: buildLoopChildArmPlan({
@@ -393,8 +413,10 @@ export function buildLoopChildConditionalsPlan(
         wrap,
         loopParam,
         loopParamBindings,
+        loopIndex,
         condId: cond.slotId,
       }),
+      ...(cond.readsPreamble && { readsPreamble: true }),
     })
   }
   return plans
@@ -429,6 +451,7 @@ export function buildArmAttrsPlan(
         attrName: attr.attrName,
         wrappedExpression: wrap(attr.expression),
         meta: pickAttrMeta(attr),
+        ...(attr.readsPreamble && { readsPreamble: true }),
       })),
     })
   }
@@ -455,12 +478,14 @@ interface BuildLoopChildArmArgs {
   wrap: (expr: string) => string
   loopParam: string
   loopParamBindings?: readonly LoopParamBinding[]
+  /** Loop's index param name, when it declares one (#2861). */
+  loopIndex?: string | null
   /** The enclosing conditional's own slot id — threaded to `buildBranchInnerLoopsPlan`'s `condSlotId` (#2705). */
   condId: string
 }
 
 function buildLoopChildArmPlan(args: BuildLoopChildArmArgs): LoopChildArmPlan {
-  const { branch, wrap, loopParam, loopParamBindings, condId } = args
+  const { branch, wrap, loopParam, loopParamBindings, loopIndex, condId } = args
   return {
     events: buildBranchEventBindingsPlan({
       events: branch.events,
@@ -476,6 +501,7 @@ function buildLoopChildArmPlan(args: BuildLoopChildArmArgs): LoopChildArmPlan {
       condSlotId: condId,
       outerLoopParam: loopParam,
       outerLoopParamBindings: loopParamBindings,
+      outerLoopIndex: loopIndex,
       wrapOuter: wrap,
     }),
     nestedConditionals: buildLoopChildConditionalsPlan({
@@ -484,6 +510,7 @@ function buildLoopChildArmPlan(args: BuildLoopChildArmArgs): LoopChildArmPlan {
       wrap,
       loopParam,
       loopParamBindings,
+      loopIndex,
     }),
     attrs: buildArmAttrsPlan(branch.reactiveAttrs, wrap),
     texts: buildArmTextsPlan(branch.reactiveTexts, wrap),

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

@@ -28,17 +28,14 @@ import {
   buildLoopChildIndexExpr,
   setIntersects,
   varSlotId,
-  wrapLoopParamAsAccessor,
 } from '../../utils.ts'
 import {
   loopKeyFn,
-  destructureLoopParam,
   buildChildRefBindings,
   buildStaticChildRefBindings,
-  buildPreambleRegionPlans,
 } from '../shared.ts'
 import { buildLoopReactiveEffectsPlan } from './build-reactive-effects.ts'
-import { buildLazyRowPlan } from './build-lazy-row.ts'
+import { buildPlainRowCore } from './build-plain-row.ts'
 import type { LazyRowScopeInfo } from './lazy-row-eligibility.ts'
 import { buildComponentLoopPlan } from './build-component-loop.ts'
 import { buildTopLevelCompositePlan } from './build-composite-loop.ts'
@@ -99,8 +96,6 @@ export function buildPlainLoopPlan(
   profileComponentName?: string,
   lazyScope?: LazyRowScopeInfo,
 ): PlainLoopPlan {
-  const wrap = (expr: string) => wrapLoopParamAsAccessor(expr, elem.param, elem.paramBindings)
-  const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(elem.param, elem.paramBindings)
   const hasReactive = elem.bindings.reactiveAttrs.length > 0
     || elem.bindings.reactiveTexts.length > 0
     || elem.bindings.conditionals.length > 0
@@ -140,14 +135,26 @@ export function buildPlainLoopPlan(
   }
 
   const arrayExpr = buildChainedArrayExpr(elem)
-  const indexParam = elem.index || '__idx'
-  const mapPreambleWrapped = elem.preamble
-    ? renderPreamble(elem.preamble, {
-        transformJs: wrap,
-        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined),
-      })
-    : ''
-  const preambleRegions = buildPreambleRegionPlans(elem.preambleRegions, elem.param, elem.paramBindings)
+
+  // Shared "wrap item → decide lazy → wrap index" core (#2859 follow-up) —
+  // see `build-plain-row.ts`'s module docstring for why this single
+  // implementation matters: a lazy-eligible loop's `LazyRowPlanData` embeds
+  // `mapPreambleWrapped` and clones from `elem.template` verbatim, and
+  // `mapArrayLazy`'s `createRow(entry, index)` hands the row a plain index
+  // NUMBER, never an accessor — wrapping unconditionally would call a number
+  // there. Lazy-row eligibility only refuses a REACTIVE binding that
+  // references the index; a non-reactive use (e.g. a `data-key` built from
+  // the index) is not gated the same way, so "lazy-eligible" does not imply
+  // "no index in the template" either.
+  const core = buildPlainRowCore({
+    loop: elem,
+    arrayExpr,
+    callSite: 'plain',
+    flatMapLeafItem: false,
+    anchored: elem.bodyIsItemConditional ?? false,
+    scope: lazyScope,
+  })
+  const { paramHead, paramUnwrap, indexParam, preambleRegions, lazyRow, wrapItem: wrap } = core
 
   return {
     kind: 'plain',
@@ -160,29 +167,21 @@ export function buildPlainLoopPlan(
     paramHead,
     paramUnwrap,
     indexParam,
-    // Lazy row graph (§9, L3). `null` for every ineligible loop, which then
-    // keeps the eager emission below byte-for-byte.
-    lazyRow: buildLazyRowPlan({
-      loop: elem,
-      arrayExpr,
-      indexParam,
-      paramUnwrap,
-      mapPreambleWrapped,
-      preambleRegionCount: preambleRegions.length,
-      callSite: 'plain',
-      flatMapLeafItem: false,
-      anchored: elem.bodyIsItemConditional ?? false,
-      scope: lazyScope,
-    }) ?? undefined,
+    lazyRow,
     // Stage 3 / D4 — js segments get the loop-param accessor wrap; jsx leaves
     // render as HTML-string templates under this loop's param context so a
     // leaf that reads the item (`r`) becomes `r()`.
-    mapPreambleWrapped,
-    template: elem.template,
+    mapPreambleWrapped: core.mapPreambleWrapped,
+    template: core.template,
     skeletonTemplate: elem.skeletonTemplate,
     skeletonPaths: elem.skeletonPaths,
     reactiveEffects: hasReactive ? buildLoopReactiveEffectsPlan(elem, profileComponentName) : null,
-    childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
+    // `elem.index` (#2859 follow-up): a ref callback closing over the loop
+    // index (`ref={el => refs[i] = el}`) must see it wrapped the same way
+    // every other reference in this row is — a row with any ref is always
+    // lazy-ineligible (`lazy-row-eligibility.ts`'s `childRefCount` gate), so
+    // there is no shared-string hazard here, unlike `mapPreambleWrapped`.
+    childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings, elem.index),
     preambleRegions,
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,
     anchored: elem.bodyIsItemConditional ?? false,
@@ -190,9 +189,10 @@ export function buildPlainLoopPlan(
     // conditional without a key is a BF023 error, but the emitted client JS
     // must still parse — an empty `anchorKeyExpr` would produce
     // `createComment(`bf-loop-i:${}`)` (a SyntaxError that breaks the whole
-    // bundle). `elem.index || '__idx'` matches `indexParam` above, so the
-    // anchor value stays consistent with the renderItem's own index param.
-    anchorKeyExpr: elem.key ? wrap(elem.key) : (elem.index || '__idx'),
+    // bundle). `indexParam` matches the renderItem head built above, and
+    // (#2859) is bound to an INDEX ACCESSOR at runtime, not a plain number —
+    // call it, same as every other reference to it in this row's body.
+    anchorKeyExpr: elem.key ? wrap(elem.key) : `${indexParam}()`,
   }
 }
 
@@ -269,7 +269,7 @@ function buildStaticLoopMaterialize(
     itemTemplate: elem.staticItemTemplate,
     mapPreamble: elem.preamble
       ? renderPreamble(elem.preamble, {
-          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings }], undefined),
+          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: elem.param, bindings: elem.paramBindings, index: elem.index }], undefined),
         })
       : '',
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,

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

@@ -0,0 +1,116 @@
+/**
+ * Shared "wrap item → decide lazy → wrap index" core for a plain loop row.
+ *
+ * `buildPlainLoopPlan` (`build-loop.ts`, `TopLevelLoop`) and
+ * `buildBranchLoopPlan` (`build-branch-loop.ts`, `BranchLoop`) both build a
+ * row from a `.map()` callback the SAME way:
+ *
+ *   1. Wrap the row's JS with ITEM-ONLY accessor rewriting (no index) — this
+ *      string must stay index-unwrapped because it is reused VERBATIM by the
+ *      lazy row plan below, which reads the index differently (a live
+ *      per-call value off `entry.index`/`createRow`'s parameter, never a
+ *      `.map()`-body call).
+ *   2. Ask `buildLazyRowPlan` for a verdict.
+ *   3. Only once lazy is ruled out (`!lazyRow`), wrap index references too,
+ *      for the eager path — `mapArrayLazy`'s `createRow` hands a row a plain
+ *      index NUMBER, so wrapping unconditionally would call a number.
+ *
+ * Before this extraction, the sequence was duplicated verbatim (mod `elem`/`loop` naming)
+ * between the two builders — exactly the "one decision, two implementations"
+ * pattern this repo's CLAUDE.md warns against, and the shape of the original
+ * #2859 CI regression (the eager index-wrap leaking into the lazy-shared
+ * string). One implementation now, called from both sites, so the decision
+ * cannot silently diverge again.
+ */
+
+import type { BranchLoop, TopLevelLoop } from '../../types.ts'
+import { wrapLoopParamAsAccessor, wrapIndexParamAsAccessor } from '../../utils.ts'
+import { destructureLoopParam, buildPreambleRegionPlans } from '../shared.ts'
+import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
+import { buildLazyRowPlan, type LazyRowPlanData } from './build-lazy-row.ts'
+import type { LazyRowScopeInfo } from './lazy-row-eligibility.ts'
+import type { PreambleRegionPlan } from './loop.ts'
+
+export interface PlainRowInputs {
+  loop: TopLevelLoop | BranchLoop
+  /** Fully-chained array expression as the CALLER emits it (branch-loop's flatMap form differs from plain's). */
+  arrayExpr: string
+  callSite: 'plain' | 'branch-plain'
+  flatMapLeafItem: boolean
+  anchored: boolean
+  scope: LazyRowScopeInfo | undefined
+}
+
+export interface PlainRowCore {
+  indexParam: string
+  paramHead: string
+  paramUnwrap: string
+  preambleRegions: readonly PreambleRegionPlan[]
+  lazyRow: LazyRowPlanData | undefined
+  /** Item-wrapped, and index-wrapped too IFF the row is NOT lazy-eligible. */
+  mapPreambleWrapped: string
+  /** Same rule as `mapPreambleWrapped`, applied to `loop.template`. */
+  template: string
+  /** Item-only wrap — exposed for the few expressions (e.g. `anchorKeyExpr`) built outside this core. */
+  wrapItem: (expr: string) => string
+}
+
+export function buildPlainRowCore(inputs: PlainRowInputs): PlainRowCore {
+  const { loop, arrayExpr, callSite, flatMapLeafItem, anchored, scope } = inputs
+
+  const wrapItem = (expr: string) => wrapLoopParamAsAccessor(expr, loop.param, loop.paramBindings)
+  const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(loop.param, loop.paramBindings)
+  const indexParam = loop.index || '__idx'
+
+  const mapPreambleWrapped = loop.preamble
+    ? renderPreamble(loop.preamble, {
+        transformJs: wrapItem,
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined),
+      })
+    : ''
+  const preambleRegions = buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings, loop.index)
+
+  // Lazy row graph (§9, L3). `undefined` for every ineligible loop, which
+  // then keeps the eager emission below byte-for-byte. Decided from the
+  // item-only-wrapped `mapPreambleWrapped` above — eligibility itself reads
+  // `loop.preamble` (raw), not this string, so which wrap it carries doesn't
+  // change the verdict.
+  const lazyRow = buildLazyRowPlan({
+    loop,
+    arrayExpr,
+    indexParam,
+    paramUnwrap,
+    mapPreambleWrapped,
+    preambleRegionCount: preambleRegions.length,
+    callSite,
+    flatMapLeafItem,
+    anchored,
+    scope,
+  }) ?? undefined
+
+  // Only once lazy is ruled out is it safe to ALSO wrap index references
+  // (#2859 follow-up) — see the module docstring.
+  const mapPreambleWrappedFinal = !lazyRow && loop.index
+    ? wrapIndexParamAsAccessor(mapPreambleWrapped, loop.index)
+    : mapPreambleWrapped
+  // `loop.templateIndexed` is a second structured render (index wrapped at
+  // IR time, `collect-elements.ts`) rather than a post-hoc regex pass over
+  // `loop.template` — a word-boundary regex over assembled HTML can match a
+  // bare tag name colliding with the index identifier (`<i>` -> `<i()>`,
+  // #2868). Falls back to `loop.template` for the rare shape that doesn't
+  // populate it (e.g. a flatMap projection loop).
+  const templateFinal = !lazyRow && loop.index
+    ? (loop.templateIndexed ?? loop.template)
+    : loop.template
+
+  return {
+    indexParam,
+    paramHead,
+    paramUnwrap,
+    preambleRegions,
+    lazyRow,
+    mapPreambleWrapped: mapPreambleWrappedFinal,
+    template: templateFinal,
+    wrapItem,
+  }
+}