@barefootjs/jsx 0.34.0 → 0.35.0

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

@@ -11,14 +11,13 @@
  */
 
 import type { BranchLoop } from '../../types.ts'
-import { buildChainedArrayExpr, varSlotId, wrapLoopParamAsAccessor } from '../../utils.ts'
+import { buildChainedArrayExpr, varSlotId } from '../../utils.ts'
 import { buildBranchCompositePlan } from './build-composite-loop.ts'
 import { buildBranchLoopDelegationPlan } from './build-event-delegation.ts'
 import { buildReactiveEffectsPlan } 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 { destructureLoopParam, loopKeyFn, buildChildRefBindings, buildPreambleRegionPlans } from '../shared.ts'
-import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
+import { loopKeyFn, buildChildRefBindings } from '../shared.ts'
 import type {
   BranchCompositeLoopPlan,
   BranchLoopPlan,
@@ -44,7 +43,6 @@ export function buildBranchLoopPlan(
     return composite
   }
 
-  const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(loop.param, loop.paramBindings)
   const hasReactiveEffects = loop.bindings.reactiveAttrs.length > 0
     || loop.bindings.reactiveTexts.length > 0
     || loop.bindings.conditionals.length > 0
@@ -54,14 +52,18 @@ export function buildBranchLoopPlan(
   const arrayExpr = fm
     ? `(${buildChainedArrayExpr(loop)}).flatMap(${fm.params} => ${fm.body})`
     : buildChainedArrayExpr(loop)
-  const indexParam = loop.index || '__idx'
-  const 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),
-      })
-    : ''
-  const preambleRegions = buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings)
+
+  // Shared "wrap item → decide lazy → wrap index" core (#2859 follow-up) —
+  // see `build-plain-row.ts`'s module docstring for the full rationale.
+  const core = buildPlainRowCore({
+    loop,
+    arrayExpr,
+    callSite: 'branch-plain',
+    flatMapLeafItem: Boolean(fm),
+    anchored: false,
+    scope: lazyScope,
+  })
+  const { paramHead, paramUnwrap, indexParam, preambleRegions, lazyRow } = core
   const plan: BranchPlainLoopPlan = {
     kind: 'plain',
     rowConstruction: 'string-template',
@@ -78,21 +80,10 @@ export function buildBranchLoopPlan(
     indexParam,
     // Wrap loop-param references to signal-accessor form so the preamble
     // matches the template literal's already-wrapped reads (#1065).
-    mapPreambleWrapped,
+    mapPreambleWrapped: core.mapPreambleWrapped,
     // Lazy row graph (§9, L3) — undefined for every ineligible loop.
-    lazyRow: buildLazyRowPlan({
-      loop,
-      arrayExpr,
-      indexParam,
-      paramUnwrap,
-      mapPreambleWrapped,
-      preambleRegionCount: preambleRegions.length,
-      callSite: 'branch-plain',
-      flatMapLeafItem: Boolean(fm),
-      anchored: false,
-      scope: lazyScope,
-    }) ?? undefined,
-    template: loop.template,
+    lazyRow,
+    template: core.template,
     reactiveEffects: hasReactiveEffects
       ? buildReactiveEffectsPlan({
           attrs: loop.bindings.reactiveAttrs,
@@ -100,11 +91,12 @@ export function buildBranchLoopPlan(
           conditionals: loop.bindings.conditionals,
           loopParam: loop.param,
           loopParamBindings: loop.paramBindings,
+          loopIndex: loop.index,
           profileComponentName,
         })
       : null,
     eventDelegation: buildBranchLoopDelegationPlan(loop, cv, profileComponentName),
-    childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings),
+    childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings, loop.index),
     preambleRegions,
     bodyIsMultiRoot: loop.bodyIsMultiRoot ?? false,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${containerSlotId}` : undefined,

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

@@ -34,8 +34,8 @@ import { internalInvariant } from '../../../errors.ts'
 /** @internal — prefer `buildLoopPlan`. */
 export function buildComponentLoopPlan(elem: TopLevelLoop, profileComponentName?: string): ComponentLoopPlan {
   const { name } = elem.childComponent!
-  const propsExpr = buildComponentPropsExpr(elem.childComponent!, elem.param)
-  const keyExpr = wrapLoopParamAsAccessor(elem.key || '__idx', elem.param, elem.paramBindings)
+  const propsExpr = buildComponentPropsExpr(elem.childComponent!, elem.param, undefined, elem.index)
+  const keyExpr = wrapLoopParamAsAccessor(elem.key || '__idx', elem.param, elem.paramBindings, elem.index)
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(elem.param, elem.paramBindings)
 
   // A component-root loop's preamble is JS-only by construction: Phase 1
@@ -47,7 +47,7 @@ export function buildComponentLoopPlan(elem: TopLevelLoop, profileComponentName?
   // that let a JSX-bearing preamble through is missing, not this line.
   const mapPreambleWrapped = elem.preamble
     ? renderPreamble(elem.preamble, {
-        transformJs: text => wrapLoopParamAsAccessor(text, elem.param, elem.paramBindings),
+        transformJs: text => wrapLoopParamAsAccessor(text, elem.param, elem.paramBindings, elem.index),
         renderLeaf: () => {
           internalInvariant(false, 'component-root loop received a JSX-bearing preamble — Phase 1 should have refused it')
         },
@@ -62,13 +62,14 @@ export function buildComponentLoopPlan(elem: TopLevelLoop, profileComponentName?
       : false
     const rawChildrenExpr = isTextOnly ? irChildrenToJsExpr(comp.children!) : null
     const childrenFreeIds = isTextOnly && comp.children ? irChildrenFreeIds(comp.children) : undefined
-    const childrenRefsLoop = rawChildrenExpr != null && childrenFreeIds != null && childrenFreeIds.has(elem.param)
+    const childrenRefsLoop = rawChildrenExpr != null && childrenFreeIds != null
+      && (childrenFreeIds.has(elem.param) || (!!elem.index && childrenFreeIds.has(elem.index)))
     return {
       componentName: comp.name,
       selector: buildCompSelector(comp),
-      propsExpr: buildComponentPropsExpr(comp, elem.param),
+      propsExpr: buildComponentPropsExpr(comp, elem.param, undefined, elem.index),
       childrenTextEffect: childrenRefsLoop
-        ? { wrappedChildren: wrapLoopParamAsAccessor(rawChildrenExpr!, elem.param, elem.paramBindings) }
+        ? { wrappedChildren: wrapLoopParamAsAccessor(rawChildrenExpr!, elem.param, elem.paramBindings, elem.index) }
         : null,
     }
   })
@@ -98,7 +99,7 @@ export function buildComponentLoopPlan(elem: TopLevelLoop, profileComponentName?
     // the per-item factory has no `__el` handle to invoke. Still required
     // by the type so the structural invariant (every variant has a
     // `childRefs`) is preserved; populated as empty.
-    childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
+    childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings, elem.index),
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${elem.slotId}` : undefined,
     childConditionalEffects: hasChildConds
       ? buildReactiveEffectsPlan({
@@ -107,6 +108,7 @@ export function buildComponentLoopPlan(elem: TopLevelLoop, profileComponentName?
           conditionals: elem.bindings.conditionals,
           loopParam: elem.param,
           loopParamBindings: elem.paramBindings,
+          loopIndex: elem.index,
           profileComponentName,
         })
       : null,

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

@@ -31,7 +31,7 @@ export function buildTopLevelCompositePlan(elem: TopLevelLoop, profileComponentN
   const nestedComps = elem.nestedComponents!
   const depthLevels = buildDepthLevels(elem.innerLoops ?? [], nestedComps, elem.bindings.events)
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(elem.param, elem.paramBindings)
-  const wrap = (expr: string) => wrapLoopParamAsAccessor(expr, elem.param, elem.paramBindings)
+  const wrap = (expr: string) => wrapLoopParamAsAccessor(expr, elem.param, elem.paramBindings, elem.index)
 
   const outerCompsByDepth = nestedComps.filter(c => !c.loopDepth || c.loopDepth === 0)
 
@@ -48,13 +48,13 @@ export function buildTopLevelCompositePlan(elem: TopLevelLoop, profileComponentN
     mapPreambleWrapped: elem.preamble
       ? renderPreamble(elem.preamble, {
           transformJs: wrap,
-          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),
         })
       : '',
     template: elem.template,
     outerComps: filterCondCompsOut(outerCompsByDepth, elem.bindings.conditionals),
     outerEvents: elem.bindings.events.filter(ev => ev.nestedLoops.length === 0),
-    childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
+    childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings, elem.index),
     innerLoops: buildInnerLoopsPlan({
       levels: depthLevels,
       parentElVar: '__el',
@@ -63,6 +63,7 @@ export function buildTopLevelCompositePlan(elem: TopLevelLoop, profileComponentN
     }),
     loopParam: elem.param,
     loopParamBindings: elem.paramBindings,
+    loopIndex: elem.index,
     reactiveEffects: hasReactive(elem)
       ? buildReactiveEffectsPlan({
           attrs: elem.bindings.reactiveAttrs,
@@ -70,6 +71,7 @@ export function buildTopLevelCompositePlan(elem: TopLevelLoop, profileComponentN
           conditionals: elem.bindings.conditionals,
           loopParam: elem.param,
           loopParamBindings: elem.paramBindings,
+          loopIndex: elem.index,
           profileComponentName,
         })
       : null,
@@ -88,7 +90,7 @@ export function buildBranchCompositePlan(loop: BranchLoop, cv: string, profileCo
   const childEvents = loop.bindings.events
   const depthLevels = buildDepthLevels(innerLoops, nestedComps, childEvents)
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(loop.param, loop.paramBindings)
-  const wrap = (expr: string) => wrapLoopParamAsAccessor(expr, loop.param, loop.paramBindings)
+  const wrap = (expr: string) => wrapLoopParamAsAccessor(expr, loop.param, loop.paramBindings, loop.index)
 
   const outerCompsByDepth = nestedComps.filter(c => !c.loopDepth || c.loopDepth === 0)
 
@@ -108,13 +110,13 @@ export function buildBranchCompositePlan(loop: BranchLoop, cv: string, profileCo
     mapPreambleWrapped: loop.preamble
       ? renderPreamble(loop.preamble, {
           transformJs: wrap,
-          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined),
+          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings, index: loop.index }], undefined),
         })
       : '',
     template: loop.template,
     outerComps: filterCondCompsOut(outerCompsByDepth, loop.bindings.conditionals),
     outerEvents: childEvents.filter(ev => ev.nestedLoops.length === 0),
-    childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings),
+    childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings, loop.index),
     innerLoops: buildInnerLoopsPlan({
       levels: depthLevels,
       parentElVar: '__el',
@@ -123,6 +125,7 @@ export function buildBranchCompositePlan(loop: BranchLoop, cv: string, profileCo
     }),
     loopParam: loop.param,
     loopParamBindings: loop.paramBindings,
+    loopIndex: loop.index,
     reactiveEffects: hasReactiveBranch(loop)
       ? buildReactiveEffectsPlan({
           attrs: loop.bindings.reactiveAttrs,
@@ -130,6 +133,7 @@ export function buildBranchCompositePlan(loop: BranchLoop, cv: string, profileCo
           conditionals: loop.bindings.conditionals,
           loopParam: loop.param,
           loopParamBindings: loop.paramBindings,
+          loopIndex: loop.index,
           profileComponentName,
         })
       : null,

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

@@ -161,11 +161,11 @@ function buildReactiveEmit(
   outerLoopParam?: string,
   outerLoopParamBindings?: readonly LoopParamBinding[],
 ): 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 +202,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,
@@ -241,16 +241,16 @@ function buildReactiveEmit(
     const leafLoopParams = outerLoopParam
       ? [
           { param: outerLoopParam, bindings: outerLoopParamBindings },
-          { param: inner.param, bindings: inner.paramBindings },
+          { 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

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,7 +218,7 @@ export function decideLazyRow(args: BuildLazyRowArgs): {
   const condFacts: LazyConditionalFacts[] = []
   let conditionalRefusal: string | null = null
   for (const cond of rawConditionals) {
-    const verdict = analyzeLazyConditional(cond, args.indexParam, {
+    const verdict = analyzeLazyConditional(cond, {
       whenTrueHtml: addCondAttrToTemplate(wrap(cond.whenTrueHtml), cond.slotId),
       whenFalseHtml: addCondAttrToTemplate(wrap(cond.whenFalseHtml), cond.slotId),
     })
@@ -374,6 +385,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

@@ -234,8 +234,8 @@ export function buildBranchInnerLoopsPlan(
     const inner = innerLoops[i]
     if (!inner.refsOuterParam || !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 +251,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.

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,110 @@
+/**
+ * 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
+  const templateFinal = !lazyRow && loop.index
+    ? wrapIndexParamAsAccessor(loop.template, loop.index)
+    : loop.template
+
+  return {
+    indexParam,
+    paramHead,
+    paramUnwrap,
+    preambleRegions,
+    lazyRow,
+    mapPreambleWrapped: mapPreambleWrappedFinal,
+    template: templateFinal,
+    wrapItem,
+  }
+}

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

@@ -52,6 +52,8 @@ export interface BuildReactiveEffectsArgs {
   conditionals: readonly LoopChildConditional[] | undefined
   loopParam: string
   loopParamBindings?: readonly LoopParamBinding[]
+  /** This loop's index param name, when it declares one (#2859). */
+  loopIndex?: string | null
   /** Owning component name in profile mode (#1690, SR3) — else undefined. */
   profileComponentName?: string
 }
@@ -60,8 +62,8 @@ export interface BuildReactiveEffectsArgs {
 export function buildReactiveEffectsPlan(
   args: BuildReactiveEffectsArgs,
 ): ReactiveEffectsPlan {
-  const { attrs, texts, conditionals, loopParam, loopParamBindings, profileComponentName } = args
-  const wrap = (expr: string) => wrapLoopParamAsAccessor(expr, loopParam, loopParamBindings)
+  const { attrs, texts, conditionals, loopParam, loopParamBindings, loopIndex, profileComponentName } = args
+  const wrap = (expr: string) => wrapLoopParamAsAccessor(expr, loopParam, loopParamBindings, loopIndex)
 
   // 1. Group attrs by slot, preserving declaration order (Map insertion order
   //    matches the legacy iteration that produced byte-identical output).
@@ -175,6 +177,7 @@ export function buildLoopReactiveEffectsPlan(elem: TopLevelLoop, profileComponen
     conditionals: elem.bindings.conditionals,
     loopParam: elem.param,
     loopParamBindings: elem.paramBindings,
+    loopIndex: elem.index,
     profileComponentName,
   })
 }

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

@@ -47,9 +47,11 @@
  *     defeating the hoist. (A literal `${` in authored TEXT would also refuse
  *     here; that is the safe direction — a false refusal costs the eager
  *     fallback, a false accept would ship a frozen arm.)
- *  4. **The condition does not read the loop INDEX.** `applyItem` and
- *     `applyOuter` have no index parameter, the same reason
- *     `ClassifiedLazyBinding.referencesIndex` refuses a binding.
+ *  4. (#2859 follow-up) A condition MAY read the loop index — it is
+ *     classified like any other binding (`classifyLazyBinding` in
+ *     `lazy-row-eligibility.ts`), which forces it into `applyItem` so a
+ *     reorder (a position change the reconciler tracks on `entry.index`)
+ *     re-evaluates it, not just an item change.
  *
  * Everything refused carries a specific reason, which `lazyRowEligibility`
  * passes through unchanged.
@@ -99,13 +101,9 @@ function wiringOn(branch: LoopChildBranchSummary): string[] {
 
 /**
  * Decide whether `cond` can be driven from the loop-level apply bodies.
- *
- * `indexParam` is the loop's index parameter name as the emitter uses it
- * (`elem.index || '__idx'`); a condition reading it is refused.
  */
 export function analyzeLazyConditional(
   cond: LoopChildConditional,
-  indexParam: string,
   arms: PreparedArms,
 ): LazyConditionalAnalysis {
   for (const [label, branch] of [['true', cond.whenTrue], ['false', cond.whenFalse]] as const) {
@@ -135,9 +133,12 @@ export function analyzeLazyConditional(
   if (!cond.conditionFreeIdentifiers) {
     return NO(`conditional on slot ${cond.slotId}: condition has no analyzable identifier set`)
   }
-  if (cond.conditionFreeIdentifiers.has(indexParam)) {
-    return NO(`conditional on slot ${cond.slotId}: condition reads the loop index parameter '${indexParam}'`)
-  }
+  // A condition reading the loop index (#2859 follow-up, widening from a hard
+  // refusal) is no longer refused here: the caller classifies the condition
+  // like any other binding (`classifyLazyBinding` in `lazy-row-eligibility.ts`),
+  // which forces `readsItem: true` for an index reference — the reconciler
+  // delivers the row's current position on `entry.index` the same way it
+  // delivers the item, so the condition is re-evaluated on a reorder too.
 
   return {
     lazySafe: true,