@barefootjs/jsx 0.34.0 → 0.35.1

package/src/ir-to-client-js/reactivity.ts

@@ -38,15 +38,27 @@ import { identifierCallPattern } from '../identifier-pattern.ts'
  * `index` field through before this fix (see each call site's own
  * `undefined`/omitted-arg default), so `undefined` here still means "not
  * guarded," not "no index param."
+ *
+ * `parentScope` (#2861): stacks this loop-row frame on top of an
+ * ENCLOSING loop's own scope, rather than always starting from
+ * `BindingScope.EMPTY` — for a nested `.map()` inside another `.map()`'s
+ * JSX body. `BindingScope.lookup`/`valueBoundNames` search innermost-first
+ * across every frame, so a row expression referencing the OUTER loop's
+ * item/index (with no dependency on the INNER loop's own item/index or any
+ * signal) is still granted a slot and classified reactive, instead of
+ * silently returning `'none'` because only the inner-most frame was ever
+ * visible. Omitted (or `undefined`) for a loop with no enclosing loop —
+ * identical to the pre-#2861 shape.
  */
 export function buildLoopRowScope(
   loopParam?: string,
   loopParamBindings?: readonly LoopParamBinding[],
   preambleNames?: ReadonlySet<string>,
   loopIndex?: string | null,
+  parentScope?: BindingScope,
 ): BindingScope | undefined {
   if (!loopParam) return undefined
-  return BindingScope.EMPTY.enterLoopRow({
+  return (parentScope ?? BindingScope.EMPTY).enterLoopRow({
     param: loopParam,
     paramBindings: loopParamBindings,
     index: loopIndex,
@@ -274,14 +286,28 @@ function needsEffectWrapperCore(
 /**
  * Why a given expression should be treated as reactive inside a loop item.
  *
- * Surfaces the two distinct reasons loop-child collectors care about:
+ * Surfaces the three distinct reasons loop-child collectors care about:
  * - `signal-or-memo-or-prop` — the expression reads a signal getter, a memo,
  *   or a prop name (what `needsEffectWrapper` already classifies).
- * - `loop-param` — the expression reads the loop parameter, which becomes a
- *   per-item signal accessor at runtime; the string-level `needsEffectWrapper`
- *   does not know about loop params.
+ * - `loop-param` — the expression reads the loop's item (or a destructured
+ *   binding of it), which becomes a per-item signal accessor at runtime;
+ *   the string-level `needsEffectWrapper` does not know about loop params.
+ * - `loop-index` (#2861) — the expression reads ONLY the loop's index
+ *   parameter (`.map((item, i) => ...)`'s `i`), with no item/signal/memo/prop
+ *   read anywhere else in it (e.g. bare `{i}`, `class={i % 2 === 0 ? …}`).
+ *   `mapArray`/`mapArrayAnchored` hand `renderItem` an index ACCESSOR
+ *   exactly like the item accessor (#2859/#2860), and `mapArrayLazy` tracks
+ *   a row's position on `entry.index` exactly like `entry.item` — but
+ *   before this classification existed, nothing ever put such an
+ *   expression in front of that machinery in the first place: Phase 1
+ *   (`jsx-to-ir.ts`'s `referencesLoopParam`) already grants it a patchable
+ *   slot via `BindingScope.valueBoundNames()` (item/index/destructure
+ *   together), while this function — Phase 2 — had no equivalent case for
+ *   the index alone, so the slot was written once at row-creation time and
+ *   never revisited.
  *
- * `none` means neither applies and the collector can skip the expression.
+ * `none` means none of the three applies and the collector can skip the
+ * expression.
  *
  * Consolidates the duplicated reactive-classification check shared by
  * `collectLoopChildReactiveTexts`, `collectLoopChildReactiveAttrs`, and
@@ -291,37 +317,53 @@ export type ReactivitySource =
   | { kind: 'none' }
   | { kind: 'signal-or-memo-or-prop' }
   | { kind: 'loop-param'; param: string }
+  | { kind: 'loop-index'; param: string }
 
 /**
  * Classify a (constant-expanded) expression as reactive inside a loop item.
- * See `ReactivitySource` for the two reasons we care about. Loop-param
- * matching takes precedence so `loop-param` is reported even when the
- * expression also reads a signal — the `kind` is purely informational and
- * collectors only care about `kind !== 'none'`.
+ * See `ReactivitySource` for the three reasons we care about. Loop-param
+ * and loop-index matching take precedence so one of them is reported even
+ * when the expression also reads a signal — the `kind` is purely
+ * informational and collectors only care about `kind !== 'none'`.
+ *
+ * Takes the row's `BindingScope` (#2482) rather than a raw `(loopParam,
+ * loopParamBindings)` pair so this reads the EXACT SAME query Phase 1's
+ * `referencesLoopParam` reads (`scope.valueBoundNames()` — item/index/
+ * destructure together) to decide whether an expression gets a patchable
+ * slot at all. `undefined` means no enclosing loop.
+ *
+ * For destructured `.map()` callbacks (#951), a `'destructure'`-sourced
+ * binding is reported as `loop-param` — the pattern text itself (e.g.
+ * `{ id, label }`) never word-matches on a bare binding like `id`, so
+ * iterating `valueBoundNames()` (rather than testing the raw param text)
+ * is what catches a destructured reference at all.
  *
- * For destructured `.map()` callbacks (#951), `loopParamBindings` lists each
- * destructured binding name; any reference to one of those names is treated
- * as a `loop-param` hit. The pattern text itself (e.g. `{ id, label }`)
- * never word-matches on a bare binding like `id`, so the straight
- * `loopParam` check misses destructured references without this widening.
+ * Item/destructure bindings are checked before the index so `loop-param`
+ * wins when an expression reads both (e.g. `` `${item.id}-${i}` ``) — this
+ * only affects which `kind` is reported, since every caller of this
+ * function besides the two `ReactivitySource`-typed union members simply
+ * tests `.kind !== 'none'`.
  */
 export function classifyReactivity(
   expr: string,
   ctx: ClientJsContext,
-  loopParam?: string,
-  loopParamBindings?: readonly LoopParamBinding[],
+  scope: BindingScope | undefined,
   freeIdentifiers?: ReadonlySet<string>,
 ): ReactivitySource {
   const has = (name: string): boolean =>
     freeIdentifiers ? freeIdentifiers.has(name) : tokenContainsIdent(expr, name)
-  if (loopParamBindings && loopParamBindings.length > 0) {
-    for (const b of loopParamBindings) {
-      if (has(b.name)) {
-        return { kind: 'loop-param', param: loopParam ?? b.name }
+  if (scope) {
+    let indexHit: string | undefined
+    for (const name of scope.valueBoundNames()) {
+      if (!has(name)) continue
+      const source = scope.lookup(name)?.binding.source
+      if (source === 'index') {
+        indexHit ??= name
+        continue
       }
+      return { kind: 'loop-param', param: name }
     }
-  } else if (loopParam && has(loopParam)) {
-    return { kind: 'loop-param', param: loopParam }
+    if (indexHit) return { kind: 'loop-index', param: indexHit }
   }
   if (needsEffectWrapper(expr, ctx, freeIdentifiers)) {
     return { kind: 'signal-or-memo-or-prop' }
@@ -666,9 +708,11 @@ export function collectLoopChildReactiveTexts(
   stopAtReactiveConditionals = false,
   preambleNames?: ReadonlySet<string>,
   loopIndex?: string | null,
+  /** Enclosing loop's own scope, for a NESTED loop (#2861) — see `buildLoopRowScope`. */
+  parentScope?: BindingScope,
 ): LoopChildReactiveText[] {
   const texts: LoopChildReactiveText[] = []
-  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex)
+  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex, parentScope)
   walkIR(node, false, {
     // Skip loop/async/if-statement subtrees — the original walker omitted
     // them; they have their own scopes (inner-loop reconciliation, async
@@ -696,7 +740,7 @@ export function collectLoopChildReactiveTexts(
       // `classifyReactivity` can't see through) still gets an update
       // effect instead of silently freezing at its SSR value (#2282).
       const reactive =
-        classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind !== 'none'
+        classifyReactivity(expanded.expr, ctx, scope, expanded.freeIds).kind !== 'none'
         || decideWrapFromAstFlags(n).wrap
       if (!reactive) return
       texts.push({
@@ -746,9 +790,11 @@ export function collectLoopChildReactiveAttrs(
   stopAtReactiveConditionals = false,
   preambleNames?: ReadonlySet<string>,
   loopIndex?: string | null,
+  /** Enclosing loop's own scope, for a NESTED loop (#2861) — see `buildLoopRowScope`. */
+  parentScope?: BindingScope,
 ): LoopChildReactiveAttr[] {
   const attrs: LoopChildReactiveAttr[] = []
-  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex)
+  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex, parentScope)
   traverseElements(node, (el) => {
     if (el.slotId) {
       for (const attr of el.attrs) {
@@ -799,7 +845,7 @@ export function collectLoopChildReactiveAttrs(
           preambleNames.size > 0 &&
           anyNameIn(expanded.freeIds ?? extractFreeIdentifiersFromText(expanded.expr), preambleNames)
         const reactive =
-          classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind !== 'none'
+          classifyReactivity(expanded.expr, ctx, scope, expanded.freeIds).kind !== 'none'
           || readsPreamble
           || attr.callsReactiveGetters
           || attr.hasFunctionCalls

package/src/ir-to-client-js/safe-html.ts

@@ -0,0 +1,243 @@
+/**
+ * Escape-by-default for client-JS HTML template strings (#2795).
+ *
+ * Every builder in `html-template.ts` assembles a JS template literal whose
+ * `${...}` holes are evaluated in the browser and parsed as HTML
+ * (`innerHTML`). Whether a hole's value is escaped used to be an OPT-IN each
+ * builder remembered separately — `escapeInClientTemplate` on the IR node, a
+ * pre-baked `escapeText(...)` string in `templateExpr`, an
+ * `escapeLeafTextExpressions` rewrite pass, and a hand-rolled `escapeText`
+ * in `buildPreambleRegionPlans` — and a forgotten opt-in shipped raw text
+ * twice (#1694, #2765/#2792). This module inverts that:
+ *
+ *   - `SafeHtml` is a compile-time nominal brand (the `TsxSourceText`
+ *     precedent, `types.ts`) on a JS EXPRESSION STRING meaning "when this
+ *     evaluates in the client template, the result is HTML that is safe to
+ *     concatenate in". Nothing outside this module can construct one, so a
+ *     `SafeHtml` value is the compiler vouching for itself — unlike the
+ *     runtime `bfMarkup()` brand (`@barefootjs/client/runtime`), which
+ *     vouches for a value the compiler never saw.
+ *   - `interp` is the ONLY way to turn a value into a `${...}` hole, and it
+ *     accepts `SafeHtml` only. A builder holding a plain `string` cannot
+ *     splice it: it must either go through a named producer below (each of
+ *     which documents WHY its output is safe) or through `spliceChildValue`,
+ *     the door for a child-position expression, whose default is
+ *     `escapeText(...)`.
+ *
+ * The runtime dispatch that already existed for values the compiler cannot
+ * classify statically is unchanged: a branch-slot value still goes through
+ * `__bfSlot` (may be a live Node), a claim-plan `'markup'` slot still goes
+ * through `escapeTextOrMarkup` (may be a `bfMarkup()`-branded prop). Those
+ * are producers here too — they escape internally, so their output is safe
+ * by construction.
+ *
+ * Attribute-value holes (`escapeAttr`, `spreadAttrs`) are a separate,
+ * always-on path in `html-template.ts` and are not routed through this
+ * module; `client-template-escape-soundness.test.ts` pins their count.
+ */
+
+import type { IRExpression } from '../types.ts'
+
+/**
+ * A JS expression string that evaluates, in the client template, to HTML
+ * safe to splice raw. Branded at construction by the producers below; only
+ * `interp` consumes it.
+ */
+export type SafeHtml = string & { readonly __safeHtmlBrand: unique symbol }
+
+/** The single place the brand is applied. Module-private on purpose. */
+function safeHtml(expr: string): SafeHtml {
+  return expr as SafeHtml
+}
+
+/**
+ * Emit a `${...}` hole. The parameter type is the whole mechanism: a builder
+ * that has only a `string` in hand cannot call this, so "forgot to escape"
+ * is a type error at the splice, not a runtime surprise in the browser.
+ */
+export function interp(span: SafeHtml): string {
+  return `\${${span}}`
+}
+
+// ---------------------------------------------------------------------------
+// Producers — escaping forms. Each wraps a runtime helper from
+// `@barefootjs/client/runtime` (see `imports.ts`'s allowlist) that escapes
+// its own input.
+// ---------------------------------------------------------------------------
+
+/** `escapeText(expr)` — the default for any child-position value. */
+export function escapedText(expr: string): SafeHtml {
+  return safeHtml(`escapeText(${expr})`)
+}
+
+/**
+ * `escapeTextOrMarkup(expr)` — `escapeText`'s strict superset that unwraps a
+ * `bfMarkup()`-branded value raw (#2651). Used only for a slot whose
+ * REACTIVE claim writer is `kind: 'markup'` (`markup-slots.ts`), so the
+ * initial render and the update agree on whether the slot may carry a
+ * compiler-built JSX prop value.
+ */
+export function escapedTextOrMarkup(expr: string): SafeHtml {
+  return safeHtml(`escapeTextOrMarkup(${expr})`)
+}
+
+/**
+ * `__bfSlot(expr, slots)` — a conditional-branch `template()` value. The
+ * runtime returns raw `<!--bf-slot:N-->` markers for live Nodes (spliced
+ * back by `insert()`) and `escapeText`s every string itself
+ * (`branch-slot.ts`). Wrapping this in another escape corrupts the markers
+ * and drops slotted content (the #1694 regression) — hence a producer, not
+ * an input to `escapedText`.
+ */
+export function branchSlotValue(expr: string, slotsVar: string): SafeHtml {
+  return safeHtml(`__bfSlot(${expr}, ${slotsVar})`)
+}
+
+// ---------------------------------------------------------------------------
+// Producers — already-HTML forms. The value is markup the compiler or
+// runtime built (and escaped piecewise) BEFORE it reaches the hole.
+// ---------------------------------------------------------------------------
+
+/**
+ * `markupOrEmpty(expr)` — a bare `{children}` passthrough (#2775). The value
+ * is the HTML string `materializeComponent` joined from the caller's
+ * children, or `undefined` when none were passed; the helper's entire job is
+ * the nullish case. Never escaped: escaping would render real child markup
+ * as visible `&lt;span&gt;` text.
+ */
+export function childrenMarkup(expr: string): SafeHtml {
+  return safeHtml(`markupOrEmpty(${expr})`)
+}
+
+/**
+ * Stage 3 / D4 — an element-array child (`{out}`) built by an arbitrary
+ * `.map()` preamble is an array of compiled-leaf HTML strings; join it
+ * rather than let `${[...]}` `String`-comma-collapse it. Each leaf's own
+ * holes already went through `interp`, so the concatenation is exactly as
+ * safe as any other compiler-emitted fragment. Also used by
+ * `buildPreambleRegionPlans` for the region-patch effect's value so the
+ * re-render matches the row template byte-for-byte.
+ */
+export function joinedMarkup(expr: string): SafeHtml {
+  return safeHtml(`Array.isArray(${expr}) ? ${expr}.join('') : (${expr} ?? '')`)
+}
+
+/**
+ * `renderChild('Name', props, ...scopeArgs)` — a child component rendered
+ * from its registered template at runtime. Its output is that component's
+ * own compiled template, whose holes went through this module in turn.
+ */
+export function renderChildCall(registryName: string, propsExpr: string, tailArgs: string): SafeHtml {
+  return safeHtml(`renderChild('${registryName}', ${propsExpr}${tailArgs})`)
+}
+
+/**
+ * `dangerouslySetInnerHTML={{ __html: E }}` — the intentional, React-style,
+ * author-facing escape hatch, and the ONLY one: the element's content is
+ * whatever `E.__html` holds, unescaped by design (mirroring every SSR
+ * adapter's native handling). The name carries the warning so an audit of
+ * raw-markup producers (`grep dangerousInnerHtml`) finds it.
+ */
+export function dangerousInnerHtml(expr: string): SafeHtml {
+  return safeHtml(`((${expr}) ?? {}).__html ?? ''`)
+}
+
+/**
+ * `cond ? \`whenTrue\` : \`whenFalse\`` — both branches are compiled
+ * template-literal BODIES (already-assembled HTML with `interp`ed holes),
+ * not values; the condition only selects between them.
+ */
+export function conditionalMarkup(condition: string, whenTrue: string, whenFalse: string): SafeHtml {
+  return safeHtml(`${condition} ? \`${whenTrue}\` : \`${whenFalse}\``)
+}
+
+/**
+ * `array.method(params => body).join('')` — a loop rendered inline. `body`
+ * is either a compiled row template literal (\`...\`), a preamble block
+ * returning one, or a flatMap descriptor body rendered through
+ * `renderPreamble`; every hole inside it went through `interp`.
+ */
+export function mappedRowsMarkup(arrayExpr: string, method: string, params: string, body: string): SafeHtml {
+  return safeHtml(`${arrayExpr}.${method}(${params} => ${body}).join('')`)
+}
+
+/** The empty string literal — a deferred placeholder the init effect fills (#1128). */
+export const EMPTY_MARKUP: SafeHtml = safeHtml("''")
+
+// ---------------------------------------------------------------------------
+// The door for a child-position expression node.
+// ---------------------------------------------------------------------------
+
+/**
+ * Recognizes a JSX child-position expression that is exactly a reference to
+ * the reserved `children` prop — bare `children` (destructured) or
+ * `<receiver>.children` for any single-identifier receiver (`props.children`,
+ * a custom props-param name, a loop-scoped alias closing over props, ...).
+ *
+ * Deliberately LOOSER than `isTransparentFragment` (`jsx-to-ir.ts`), which
+ * runs on the TS AST with the analyzer-resolved props name in hand. This
+ * layer works on IR text with no analyzer, so any single-identifier receiver
+ * is the available approximation. The looseness costs nothing measurable: an
+ * unrelated `.children` member (a tree node's own `children` array, say) is a
+ * reactive member expression that gets a `slotId` and takes the slotted arm
+ * of `spliceChildValue` before this predicate is consulted.
+ */
+function isChildrenPassthroughExpr(expr: string): boolean {
+  return /^([A-Za-z_$][\w$]*\.)?children$/.test(expr.trim())
+}
+
+export interface ChildSpliceContext {
+  /**
+   * Set while emitting inside a conditional-branch `template()` arrow
+   * (`irToHtmlTemplate`'s `branchSlotsVar`): every value in that context is
+   * routed through `__bfSlot`, which owns its own coercion.
+   */
+  readonly branchSlotsVar?: string
+  /**
+   * Slot ids whose reactive claim writer is `kind: 'markup'`
+   * (`markupSlotIdsOf(ctx)`, `markup-slots.ts`). Absent for the loop-row /
+   * branch-row builders, whose reactive twin is a `kind: 'text'` writer
+   * (`String(...)` into `nodeValue`) — plain `escapeText` is the consistent
+   * choice there, and it is also the choice that never unwraps a
+   * `bfMarkup()`-shaped object arriving in JSON-sourced loop data.
+   */
+  readonly markupSlotIds?: ReadonlySet<string>
+}
+
+/**
+ * THE door for a child-position `IRExpression` value entering a client HTML
+ * template. Takes the caller's already-wrapped/transformed expression text
+ * (`wrapExpr` / `transformExpr` output) and decides, in exactly one place,
+ * which producer it goes through. The last arm is the default, and it
+ * escapes: there is no arm that returns `valueExpr` unwrapped.
+ *
+ * Arms, first match wins:
+ *   1. `joinArrayChild`         → `joinedMarkup`      (array of compiled leaves)
+ *   2. `branchSlotsVar`         → `branchSlotValue`   (runtime coercion, may be a Node)
+ *   3. `slotId` ∈ markupSlotIds → `escapedTextOrMarkup`
+ *   4. `slotId`                 → `escapedText`
+ *   5. `{children}` passthrough → `childrenMarkup`    (bare splice only, #2775/#2786)
+ *   6. otherwise                → `escapedText`
+ *
+ * Arm 5 tests BOTH `node.expr` (the original source text, stable across
+ * builders) and the caller's resolved form (parens stripped): a
+ * destructured-and-renamed children (`const { children: kids } = props`)
+ * reads `kids` in the source and `(_p.children)` after substitution, and
+ * either alone misses one of the two shapes (#2786).
+ */
+export function spliceChildValue(
+  node: Pick<IRExpression, 'expr' | 'slotId' | 'joinArrayChild'>,
+  valueExpr: string,
+  cx: ChildSpliceContext,
+): SafeHtml {
+  if (node.joinArrayChild) return joinedMarkup(valueExpr)
+  if (cx.branchSlotsVar) return branchSlotValue(valueExpr, cx.branchSlotsVar)
+  if (node.slotId) {
+    return cx.markupSlotIds?.has(node.slotId) ? escapedTextOrMarkup(valueExpr) : escapedText(valueExpr)
+  }
+  const resolved = valueExpr.trim().replace(/^\(+|\)+$/g, '')
+  if (isChildrenPassthroughExpr(node.expr) || isChildrenPassthroughExpr(resolved)) {
+    return childrenMarkup(valueExpr)
+  }
+  return escapedText(valueExpr)
+}

package/src/ir-to-client-js/types.ts

@@ -400,7 +400,19 @@ export interface LoopChildRef {
 export interface BranchLoop extends LoopCore {
   kind: 'branch'
   index: string | null // Index parameter (e.g., 'i')
-  template: string     // HTML template for each item
+  template: string     // HTML template for each item, item-only wrapped (no index — see `templateIndexed`)
+  /**
+   * Same render as `template`, but with `index` also wrapped as an accessor
+   * (`i()`) — rendered structurally at IR time (`irToHtmlTemplate`'s
+   * `loopParams`), never via a post-hoc regex pass over `template` (#2868:
+   * a word-boundary regex over assembled HTML can match a bare tag name
+   * colliding with the index identifier, e.g. `<i>` -> `<i()>`). Present
+   * iff the loop declares an index; `build-plain-row.ts` picks this over
+   * `template` once lazy eligibility rules out the lazy row plan (which
+   * needs the index UNWRAPPED — `mapArrayLazy`'s `createRow` hands it a
+   * plain number, never an accessor).
+   */
+  templateIndexed?: string
   containerSlotId: string // bf slot ID of the container element (e.g., 's1' for <ul bf="s1">)
   preamble?: MapCallbackPreamble
   // Composite loop fields (loops whose body contains child components)
@@ -489,8 +501,6 @@ export interface NestedLoop extends LoopCore {
    * (and any subsequent reads) are in scope (#1052).
    */
   preamble?: MapCallbackPreamble
-  /** Whether the inner array references the outer loop param (needs reactive mapArray) */
-  refsOuterParam?: boolean
   /** Child components inside inner loop items (for initChild/createComponent) */
   childComponents?: import('../types.ts').IRLoopChildComponent[]
   /** True when this loop is inside a conditional branch (handled by insert() bindEvents instead) */
@@ -622,6 +632,12 @@ export interface TopLevelLoop extends LoopCore {
   slotId: string
   index: string | null
   template: string
+  /**
+   * Same render as `template`, but with `index` also wrapped as an accessor
+   * (`i()`) — see `BranchLoop.templateIndexed` for why this exists as a
+   * second structured render rather than a post-hoc regex pass (#2868).
+   */
+  templateIndexed?: string
   /**
    * Per-iteration HTML template for static-array loops that need to
    * self-heal on CSR mount (#1247). Unlike `template`, this variant skips

package/src/ir-to-client-js/utils.ts

@@ -581,17 +581,63 @@ function renderLoopBindingAccess(b: LoopParamBinding, base: string): string {
  * binding name is rewritten to `__bfItem()${path}` instead of wrapping the
  * raw pattern text. `paramName` is ignored in that case — destructured
  * callbacks never expose the pattern itself as a local.
- */
-export function wrapLoopParamAsAccessor(expr: string, paramName: string, bindings?: readonly LoopParamBinding[]): string {
+ *
+ * `indexParam` (#2859): the same `.map()` callback's index parameter
+ * (`(item, i) => ...`'s `i`), when the loop declares one. `mapArray`/
+ * `mapArrayAnchored` hand `renderItem` an INDEX ACCESSOR (mirroring the item
+ * accessor) precisely so a same-key reorder — which never re-invokes
+ * `renderItem`, only pushes fresh values through the item/index signals —
+ * can keep a row's index-derived output live. A bare reference to
+ * `indexParam` is therefore rewritten the same way as the item param; a
+ * caller that never threads an index through (e.g. no second callback
+ * param) simply omits it and behavior is unchanged. Rewritten as a SEPARATE
+ * pass after the item/bindings rewrite so an index name that happens to
+ * collide with a destructured binding name is a no-op here (the binding
+ * rewrite already consumed it; `!== paramName` below only guards the plain,
+ * non-destructured case, since `bindings` and `paramName` are mutually
+ * exclusive inputs to the item rewrite above).
+ */
+export function wrapLoopParamAsAccessor(
+  expr: string,
+  paramName: string,
+  bindings?: readonly LoopParamBinding[],
+  indexParam?: string | null,
+): string {
+  let result: string
   if (bindings && bindings.length > 0) {
-    return rewriteLoopBindingRefs(expr, bindings, '__bfItem()')
+    result = rewriteLoopBindingRefs(expr, bindings, '__bfItem()')
+  } else {
+    // `paramName` is a legal JS identifier and may itself start with `$`
+    // (`$1`, `$&`, …) — a plain string replacement would risk `String.replace`
+    // reading those as backreference/whole-match sequences, so use a replacer
+    // function to insert the accessor text literally (#2592).
+    const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(paramName)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
+    result = replaceInExprContexts(expr, re, () => `${paramName}()`)
+  }
+  if (indexParam && indexParam !== paramName) {
+    result = wrapIndexParamAsAccessor(result, indexParam)
   }
-  // `paramName` is a legal JS identifier and may itself start with `$`
-  // (`$1`, `$&`, …) — a plain string replacement would risk `String.replace`
-  // reading those as backreference/whole-match sequences, so use a replacer
-  // function to insert the accessor text literally (#2592).
-  const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(paramName)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
-  return replaceInExprContexts(expr, re, () => `${paramName}()`)
+  return result
+}
+
+/**
+ * The index-only half of `wrapLoopParamAsAccessor` — same regex shape, own
+ * identifier. Factored out so `wrapLoopParamAsAccessor` can run it as a
+ * second pass regardless of which item-rewrite branch (bindings vs. plain
+ * param) ran first (#2859).
+ *
+ * Also exported standalone for `build-loop.ts`/`build-branch-loop.ts`: a
+ * plain loop's `template`/`mapPreambleWrapped` are built ONCE, before lazy
+ * eligibility is known, because the lazy row plan reuses them verbatim when
+ * this loop turns out to be lazy-eligible (`mapArrayLazy`'s `createRow`
+ * still hands the row a plain index NUMBER, never an accessor). So those two
+ * builders wrap item references up front (safe either way) and apply this
+ * index-only pass afterward, ONLY once `buildLazyRowPlan` confirms the loop
+ * is NOT going lazy.
+ */
+export function wrapIndexParamAsAccessor(expr: string, indexParam: string): string {
+  const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(indexParam)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
+  return replaceInExprContexts(expr, re, () => `${indexParam}()`)
 }
 
 /**
@@ -718,6 +764,8 @@ export function substituteLoopBindings(
 export interface LoopParamSpec {
   param: string
   bindings?: readonly LoopParamBinding[]
+  /** This loop's index parameter name, when it declares one (#2859). */
+  index?: string | null
 }
 
 /**
@@ -747,7 +795,7 @@ export function wrapExprWithLoopParams(expr: string, loopParams?: ReadonlyArray<
   let result = expr
   for (const p of loopParams) {
     const spec = typeof p === 'string' ? { param: p } : p
-    result = wrapLoopParamAsAccessor(result, spec.param, spec.bindings)
+    result = wrapLoopParamAsAccessor(result, spec.param, spec.bindings, spec.index)
   }
   return result
 }