@barefootjs/jsx 0.18.5 → 0.19.0

package/src/ir-to-client-js/control-flow/stringify/skeleton-paths.ts

@@ -0,0 +1,70 @@
+/**
+ * Turn compile-time `SkeletonSlotPaths` (html-template.ts) into the `__p`
+ * array-literal contents plus slot -> index maps consumed by
+ * `stringifyPlainLoop` / `stringifyReactiveEffects` / `emitLoopChildRefs`
+ * (perf: direct child-index paths for hoisted single-root loops, #2143).
+ *
+ * Single source of truth for `__p` ordering: `loop.ts` (which emits the
+ * array literal) and `reactive-effects.ts` (which emits the per-slot index
+ * reads) both derive their indices from the SAME `SkeletonPathPlan`, so the
+ * two can never drift out of sync.
+ */
+
+import type { SkeletonSlotPaths } from '../../html-template.ts'
+
+/**
+ * Convert a root-relative child-index path into a `.firstChild.nextSibling…`
+ * property chain off `base`. An empty path resolves to `base` itself (the
+ * slot lives on the clone root, e.g. an attr on the loop body's own tag).
+ */
+export function pathExpr(base: string, path: readonly number[]): string {
+  let expr = base
+  for (const idx of path) {
+    expr += '.firstChild'
+    if (idx > 0) expr += '.nextSibling'.repeat(idx)
+  }
+  return expr
+}
+
+export interface SkeletonPathPlan {
+  /** Expressions for the `const __p = [...]` array literal, in stable order. */
+  arrayElems: string[]
+  /** slotId -> index into `__p`, for element-anchored slots (reactive attrs, refs). */
+  elementIndexBySlot: Map<string, number>
+  /** slotId -> index into `__p`, for text-marker-anchored slots (reactive texts). */
+  textIndexBySlot: Map<string, number>
+}
+
+/**
+ * Build the `__p` plan for a hoisted loop's reactive attr / text / ref
+ * slots. A slotId absent from `skeletonPaths` (shouldn't happen for a
+ * successfully-hoisted skeleton, but handled defensively) is simply left
+ * out of both maps — its stringifier call site falls back to `qsa`/`$t`
+ * for that one slot without affecting any other slot's resolution.
+ */
+export function buildSkeletonPathPlan(
+  skeletonPaths: SkeletonSlotPaths,
+  elVar: string,
+  opts: { elementSlotIds: readonly string[]; textSlotIds: readonly string[] },
+): SkeletonPathPlan {
+  const arrayElems: string[] = []
+  const elementIndexBySlot = new Map<string, number>()
+  const textIndexBySlot = new Map<string, number>()
+
+  for (const slotId of opts.elementSlotIds) {
+    if (elementIndexBySlot.has(slotId)) continue
+    const path = skeletonPaths.elementPaths.get(slotId)
+    if (!path) continue
+    elementIndexBySlot.set(slotId, arrayElems.length)
+    arrayElems.push(pathExpr(elVar, path))
+  }
+  for (const slotId of opts.textSlotIds) {
+    if (textIndexBySlot.has(slotId)) continue
+    const path = skeletonPaths.textMarkerPaths.get(slotId)
+    if (!path) continue
+    textIndexBySlot.set(slotId, arrayElems.length)
+    arrayElems.push(pathExpr(elVar, path))
+  }
+
+  return { arrayElems, elementIndexBySlot, textIndexBySlot }
+}

package/src/ir-to-client-js/control-flow/stringify/template-parse.ts

@@ -82,6 +82,30 @@ export function templateRootIsSvg(template: string): boolean {
   return branches.every(templateRootIsSvg)
 }
 
+/**
+ * Wrap decision for MULTI-ROOT (fragment) templates, where the synthetic
+ * `<svg>` wrap swallows every sibling root at once (#2233 Copilot review).
+ *
+ * `templateRootIsSvg` inspects only the FIRST root tag. For single-root
+ * templates that's exact, but a fragment whose first root is an `<svg>`
+ * CONTAINER (`<><svg/><span/></>`) doesn't need the wrap at all — the
+ * HTML parser enters foreign content at `<svg>` on its own — and wrapping
+ * would drag the HTML siblings into the SVG namespace (`<span>` becomes an
+ * SVGUnknownElement, silently undrawn). So `<svg>`-first fragments skip
+ * the wrap; only leaf-rooted fragments (`<line>`, `<circle>`, ...) get it.
+ *
+ * Known edge (degenerate, pre-existing): an `<svg>`-first fragment with
+ * SVG-LEAF siblings (`<><svg/><line/></>`) leaves the bare leaf siblings
+ * in the HTML namespace — exactly the pre-#2219 behavior. Deciding that
+ * shape correctly needs a scan of every top-level root tag; not worth the
+ * parser until a real component hits it.
+ */
+export function multiRootTemplateNeedsSvgWrap(template: string): boolean {
+  const m = stripLeadingNonContent(template).match(/^<\s*([A-Za-z][A-Za-z0-9-]*)/)
+  if (m && m[1].toLowerCase() === 'svg') return false
+  return templateRootIsSvg(template)
+}
+
 /**
  * Strip leading whitespace and HTML comment markers (`<!-- ... -->`) so
  * that a branch like `<!--bf-cond-start:s0-->${...}<!--bf-cond-end:s0-->`
@@ -269,7 +293,7 @@ export function emitMultiRootTemplateCloneLines(
   varEl: string,
   varExtras: string,
 ): string[] {
-  const isSvg = templateRootIsSvg(template)
+  const isSvg = multiRootTemplateNeedsSvgWrap(template)
   // Wrap in `<svg>` so the parser walks into SVG foreign content; we then
   // descend one level to pick up the per-item roots.
   const innerHtmlExpr = isSvg ? `\`<svg>${template}</svg>\`` : `\`${template}\``

package/src/ir-to-client-js/csr-substitute.ts

@@ -338,6 +338,59 @@ export function extractFreeIdentifiersFromText(text: string): Set<string> {
   return extractFreeIdentifiersFromNode(expr)
 }
 
+/**
+ * Free identifiers referenced by a block of JS *statements* — e.g. an inner
+ * `.map()` callback's block-body preamble (`mapPreamble`, #1052). Unlike
+ * `extractFreeIdentifiersFromText`, which wraps its input in `(...)` to
+ * force single-expression parsing, statement text (`const x = ...;`) is
+ * not a valid expression and would fail to parse inside parens — parse it
+ * as top-level source instead. Used by nested-loop index-param reference
+ * gating (#2218).
+ */
+export function extractFreeIdentifiersFromStatementText(text: string): Set<string> {
+  if (!text || text.trim().length === 0) return new Set()
+  const sf = ts.createSourceFile(
+    '__free_ids_stmt__.ts',
+    text,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+    ts.ScriptKind.TS,
+  )
+  return extractFreeIdentifiersFromNode(sf)
+}
+
+/**
+ * Free identifiers referenced inside a template-literal-style string's
+ * `${...}` interpolations — e.g. a nested loop's per-item HTML `template`
+ * (#2218). Wraps the text in backticks and parses it as a real
+ * `TemplateExpression` so brace balancing, string literals, and nested
+ * object/array literals inside `${...}` are handled correctly by the TS
+ * parser (AST-based — never the char-class regex `extractTemplateExpressions`
+ * in `identifiers.ts` uses for its looser references-graph pass). Safe by
+ * construction: the same `template` string is embedded verbatim inside a
+ * real backtick literal at emit time (`__t.innerHTML = \`${template}\``),
+ * so wrapping it here to parse mirrors exactly how it's already used.
+ */
+export function extractFreeIdentifiersFromTemplateText(template: string): Set<string> {
+  if (!template || template.length === 0) return new Set()
+  const sf = ts.createSourceFile(
+    '__free_ids_template__.ts',
+    `(\`${template}\`);`,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+    ts.ScriptKind.TS,
+  )
+  const stmt = sf.statements[0]
+  if (!stmt || !ts.isExpressionStatement(stmt)) return new Set()
+  const expr = ts.isParenthesizedExpression(stmt.expression) ? stmt.expression.expression : stmt.expression
+  if (!ts.isTemplateExpression(expr)) return new Set()
+  const ids = new Set<string>()
+  for (const span of expr.templateSpans) {
+    for (const id of extractFreeIdentifiersFromNode(span.expression)) ids.add(id)
+  }
+  return ids
+}
+
 /**
  * Reduce a memo's `() => expr` source to the expression that should be
  * substituted in for `memoName()`. Matches the extraction done by the

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

@@ -875,6 +875,196 @@ export function buildLoopSkeletonTemplate(node: IRNode, safe: LoopSkeletonSafeSl
   }
 }
 
+/**
+ * Child-node index paths for a hoisted loop skeleton (perf, #2143): computed
+ * alongside `buildLoopSkeletonTemplate` from the SAME IR tree, so the
+ * compiler can emit direct `.firstChild`/`.nextSibling` property chains
+ * (Solid-style) instead of a per-row `qsa`/`$t` runtime lookup for every
+ * dynamic slot in the hoisted single-root loop fast path.
+ *
+ * Only ever consumed for a FRESH clone of the hoisted skeleton — hydration
+ * (`__existing`, real SSR-rendered DOM) keeps using `qsa`/`$t`, since the
+ * skeleton's empty text markers and omitted dynamic attrs don't describe the
+ * SSR-rendered tree's actual shape (see `computeSkeletonSlotPaths`).
+ */
+export interface SkeletonSlotPaths {
+  /** slotId -> childNodes-index path from the clone root to the element carrying `bf="slotId"`. Empty array = the root itself. */
+  elementPaths: ReadonlyMap<string, readonly number[]>
+  /** slotId -> path to the first Comment of the `<!--bf:slotId--><!--/-->` marker pair. */
+  textMarkerPaths: ReadonlyMap<string, readonly number[]>
+}
+
+/**
+ * Tags whose HTML-parser behavior can silently restructure or drop children
+ * relative to the naive IR-tree model (implied table sections, `<select>`/
+ * `<optgroup>` child-dropping, `<p>` auto-close, leading-newline drop in
+ * `<pre>`/`<textarea>`, `<template>` content relocating into `.content`). A
+ * skeleton containing any of these bails on path computation entirely —
+ * the loop keeps its hoisted-clone fast path, but every slot lookup falls
+ * back to `qsa`/`$t`.
+ */
+const SKELETON_PATH_HAZARD_TAGS = new Set([
+  'table', 'thead', 'tbody', 'tfoot', 'caption', 'colgroup', 'col',
+  'select', 'optgroup',
+  'p',
+  'pre', 'textarea', 'listing',
+  'template',
+  'math', // MathML foreign-content: breakout tags pop content back out, same class of hazard as SVG.
+])
+
+/**
+ * Tag groups the HTML parser force-closes when a tag from the group is
+ * nested inside ANY other open tag from the SAME group — not just an
+ * identical tag (e.g. `<h2>` inside `<h1>` closes the `<h1>`, `<dd>` inside
+ * `<dt>` closes the `<dt>`). A skeleton hitting this bails on path
+ * computation entirely (see `SKELETON_PATH_HAZARD_TAGS` doc).
+ */
+const SKELETON_PATH_FORCE_CLOSE_GROUPS: ReadonlyArray<ReadonlySet<string>> = [
+  new Set(['a']),
+  new Set(['button']),
+  new Set(['form']),
+  new Set(['option']),
+  new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+  new Set(['dd', 'dt']),
+  new Set(['li']),
+]
+
+function skeletonForceCloseGroup(tag: string): number {
+  return SKELETON_PATH_FORCE_CLOSE_GROUPS.findIndex(group => group.has(tag))
+}
+
+interface SkeletonPathState {
+  elementPaths: Map<string, readonly number[]>
+  textMarkerPaths: Map<string, readonly number[]>
+  bailed: boolean
+}
+
+/**
+ * Compute per-slot child-index paths for a loop skeleton already proven
+ * safe by `buildLoopSkeletonTemplate` — call this ONLY after that returned
+ * non-null for the same `(node, safe)` pair; it assumes the same shape
+ * guarantees (no spreads/conditionals/components/nested loops) and does not
+ * re-derive them. Returns `null` when the tree contains a parser-hazard tag
+ * (see `SKELETON_PATH_HAZARD_TAGS`) that could make the index-path model
+ * diverge from the browser's actual parsed structure.
+ */
+export function computeSkeletonSlotPaths(node: IRNode, safe: LoopSkeletonSafeSlots): SkeletonSlotPaths | null {
+  const state: SkeletonPathState = { elementPaths: new Map(), textMarkerPaths: new Map(), bailed: false }
+  walkSkeletonPathNode(node, [], safe, state, new Set())
+  if (state.bailed) return null
+  return { elementPaths: state.elementPaths, textMarkerPaths: state.textMarkerPaths }
+}
+
+function walkSkeletonPathNode(
+  node: IRNode,
+  path: readonly number[],
+  safe: LoopSkeletonSafeSlots,
+  state: SkeletonPathState,
+  forceCloseAncestors: ReadonlySet<number>,
+): void {
+  if (state.bailed || node.type !== 'element') return
+  if (SKELETON_PATH_HAZARD_TAGS.has(node.tag)) { state.bailed = true; return }
+  const groupIdx = skeletonForceCloseGroup(node.tag)
+  if (groupIdx >= 0 && forceCloseAncestors.has(groupIdx)) { state.bailed = true; return }
+  // Void elements never legally carry children; if the IR claims otherwise
+  // the browser reparses `</tag>` as stray content instead of a close tag,
+  // diverging from the naive one-node-per-element model.
+  const flatChildren = flattenSkeletonChildren(node.children)
+  if (VOID_ELEMENTS.has(node.tag) && flatChildren.length > 0) { state.bailed = true; return }
+  // Foster parenting (#2143 review): a bare `<tr>` root is intentionally NOT
+  // in SKELETON_PATH_HAZARD_TAGS (it's the common loop-row shape), but
+  // non-`td`/`th` element children — and any non-whitespace text run —
+  // directly inside it get foster-parented OUT of the row by the HTML
+  // parser, shifting every sibling index after them. Comments (the `bf:sN`
+  // marker pairs) are unaffected — comments are inserted in place even in
+  // table-related insertion modes.
+  if (node.tag === 'tr' && hasForeignTableRowContent(flatChildren)) { state.bailed = true; return }
+  if (node.slotId) state.elementPaths.set(node.slotId, path)
+  const nextAncestors = groupIdx >= 0
+    ? new Set([...forceCloseAncestors, groupIdx])
+    : forceCloseAncestors
+  walkSkeletonPathChildren(flatChildren, path, safe, state, nextAncestors)
+}
+
+/** True if `children` (already flattened) contains anything the HTML parser would foster-parent out of a `<tr>`. */
+function hasForeignTableRowContent(children: readonly IRNode[]): boolean {
+  for (const child of children) {
+    if (child.type === 'text') {
+      if (child.value.trim() !== '') return true
+      continue
+    }
+    if (child.type === 'element' && child.tag !== 'td' && child.tag !== 'th') {
+      return true
+    }
+  }
+  return false
+}
+
+/** Splice fragment children inline — a fragment contributes no DOM node of its own. */
+function flattenSkeletonChildren(children: readonly IRNode[]): IRNode[] {
+  const out: IRNode[] = []
+  for (const child of children) {
+    if (child.type === 'fragment') {
+      out.push(...flattenSkeletonChildren(child.children))
+    } else {
+      out.push(child)
+    }
+  }
+  return out
+}
+
+/**
+ * Walk one level of (already flattened) children, tracking the DOM child
+ * index as it will exist on a FRESH clone of the skeleton (empty text
+ * markers, no dynamic attrs) — not the per-row interpolated template.
+ * Mirrors the browser's text-node-merging behavior: adjacent text content
+ * (including a dropped null/undefined expression) collapses into a single
+ * Text node; an empty literal string contributes no node at all.
+ */
+function walkSkeletonPathChildren(
+  children: readonly IRNode[],
+  parentPath: readonly number[],
+  safe: LoopSkeletonSafeSlots,
+  state: SkeletonPathState,
+  forceCloseAncestors: ReadonlySet<number>,
+): void {
+  let idx = 0
+  let pendingText = false
+  for (const child of children) {
+    if (state.bailed) return
+    switch (child.type) {
+      case 'text': {
+        if (child.value === '') continue
+        if (!pendingText) idx += 1
+        pendingText = true
+        continue
+      }
+      case 'expression': {
+        if (child.expr === 'null' || child.expr === 'undefined') continue
+        if (!child.slotId || !safe.reactiveTextSlotIds.has(child.slotId)) { state.bailed = true; return }
+        state.textMarkerPaths.set(child.slotId, [...parentPath, idx])
+        idx += 2 // the marker pair: <!--bf:sN--> then <!--/-->
+        pendingText = false
+        continue
+      }
+      case 'element': {
+        walkSkeletonPathNode(child, [...parentPath, idx], safe, state, forceCloseAncestors)
+        idx += 1
+        pendingText = false
+        continue
+      }
+      case 'fragment':
+        continue // already flattened
+      default:
+        // conditional/component/loop/if-statement/provider/async/slot: none
+        // of these should reach here — buildLoopSkeletonTemplate would have
+        // already returned null for the same tree. Bail defensively.
+        state.bailed = true
+        return
+    }
+  }
+}
+
 /**
  * Generate an HTML template for composite element reconciliation.
  * Identical to irToHtmlTemplate except component nodes become placeholder
@@ -1135,6 +1325,20 @@ export interface TemplateOptions {
   csrEnv?: CsrEnv
   insideLoop?: boolean
   loopDepth?: number
+  /**
+   * Names bound by the ENCLOSING loops' callback params (item / index /
+   * destructured binding names), accumulated by the `loop` case as the
+   * recursion descends (#2222). Inside a loop body, `csrSubstitute`
+   * receives each expression in isolation — no enclosing arrow text — so
+   * its own bound-name tracking can't see the loop binding; the `loop`
+   * case instead filters these names out of the child recursion's
+   * `csrEnv`, so an inlinable const / signal / memo whose name is
+   * shadowed by a loop param never substitutes at the shadowed
+   * occurrence. Scope-accurate per nesting level (the CURRENT level's
+   * own `transformExpr` — e.g. the loop's array-source expression —
+   * keeps the unfiltered env).
+   */
+  loopBoundNames?: ReadonlySet<string>
   /** Emit `bf-s` placeholder on scoped elements inside a jsx-children prop (#1320). */
   inHoistedChildren?: boolean
   /**
@@ -1988,7 +2192,36 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
     }
 
     case 'loop': {
-      let childTemplate = node.children.map(recurseInLoop).join('')
+      // Accumulate this loop's callback-bound names and filter them out
+      // of the child recursion's substitution env (#2222): an inlinable
+      // const / signal / memo whose name the callback shadows must never
+      // substitute inside the body. Destructured callbacks contribute
+      // their individual binding names; a raw pattern-text `param` (the
+      // BF025 fallback shapes, detected by the same leading-`[`/`{` check
+      // `destructureLoopParam` uses — NOT an ASCII-identifier regex, which
+      // would drop Unicode param names like `π` and re-enable the shadow
+      // bug for that body) contributes nothing — conservatively
+      // unfiltered rather than mis-filtered.
+      const boundHere = new Set(opts.loopBoundNames ?? [])
+      if (node.paramBindings && node.paramBindings.length > 0) {
+        for (const b of node.paramBindings) boundHere.add(b.name)
+      } else if (!node.param.startsWith('[') && !node.param.startsWith('{')) {
+        boundHere.add(node.param)
+      }
+      if (node.index) boundHere.add(node.index)
+      const childEnv: CsrEnv = {
+        ...env,
+        substitutions: new Map([...env.substitutions].filter(([name]) => !boundHere.has(name))),
+      }
+      const recurseInLoopBody = (n: IRNode): string => generateCsrTemplateWithOpts(n, {
+        ...opts,
+        insideLoop: true,
+        loopDepth: loopDepth + 1,
+        inHoistedChildren: false,
+        loopBoundNames: boundHere,
+        csrEnv: childEnv,
+      })
+      let childTemplate = node.children.map(recurseInLoopBody).join('')
       // Whole-item conditional loops (#1665): prepend the per-item
       // `<!--bf-loop-i:KEY-->` anchor so `mapArrayAnchored` can track items
       // that render no element. Mirrors the `irToHtmlTemplate` loop case.
@@ -2022,7 +2255,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
       if (node.flatMapCallback) {
         let body = node.flatMapCallback.templateBody ?? node.flatMapCallback.body
         for (const frag of node.flatMapCallback.fragments) {
-          const renderedIr = recurseInLoop(frag.ir)
+          const renderedIr = recurseInLoopBody(frag.ir)
           body = body.replace(frag.placeholder, `\`${renderedIr}\``)
         }
         body = applyPropsRewrite(body, propsObjectName ?? null)

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

@@ -14,6 +14,7 @@ export const RUNTIME_IMPORT_CANDIDATES = [
   'provideContext', 'createContext', 'useContext',
   'forwardProps', 'applyRestAttrs', 'splitProps', 'spreadAttrs', 'styleToCss', 'escapeAttr', 'escapeText',
   'qsa', 'qsaItem', 'qsaChildScope', 'qsaChildScopes', 'upsertChildItem', '__slot', '__bfSlot', '__bfText',
+  'tAfter',
   // Profile mode (#1690, SR3) — turn-boundary markers around event handlers.
   'beginTurn', 'endTurn',
 ] as const

package/src/ir-to-client-js/phases/props-extraction.ts

@@ -9,7 +9,6 @@
  *   - prop has property/index access     → `?? {}`  (skipped when the
  *                                            prop is a conditional guard
  *                                            so falsy values stay falsy)
- *   - prop is optional with type info    → `?? <inferred default>`
  *   - otherwise                          → no default
  *
  * Skipped entirely when the component uses an opaque props object name
@@ -20,7 +19,7 @@
 import type { PropUsage } from '../../types.ts'
 import { propHasPropertyAccess } from '../compute-prop-usage.ts'
 import type { ClientJsContext } from '../types.ts'
-import { inferDefaultValue, PROPS_PARAM } from '../utils.ts'
+import { PROPS_PARAM } from '../utils.ts'
 
 export function emitPropsExtraction(
   lines: string[],
@@ -53,14 +52,11 @@ export function emitPropsExtraction(
       lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName} ?? []`)
     } else if (propHasPropertyAccess(usage) && !propsUsedAsConditions.has(propName)) {
       lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName} ?? {}`)
-    } else if (prop?.optional && prop?.type) {
-      const inferredDefault = inferDefaultValue(prop.type)
-      if (inferredDefault !== 'undefined') {
-        lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName} ?? ${inferredDefault}`)
-      } else {
-        lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName}`)
-      }
     } else {
+      // No synthesized default for a defaultless optional (`{ size }:
+      // { size?: number }`): the JS binding is `undefined` when absent, and
+      // a zero default would diverge from SSR (`size ?? 1` seeds 1
+      // server-side; a `_p.size ?? 0` extraction would hydrate to 0).
       lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName}`)
     }
   }

package/src/ir-to-client-js/plan/build-static-array-child-init.ts

@@ -124,6 +124,11 @@ function buildInnerLoopNestedPlan(
   innerComps: readonly IRLoopChildComponent[],
 ): InnerLoopNestedInitPlan {
   const outerIndexParam = elem.index || '__idx'
+  // The user's declared inner index name, falling back to the synthetic
+  // `__innerIdx` — same idiom as the outer `elem.index || '__idx'` above.
+  // Hardcoding the synthetic name left a referenced user index unbound and
+  // `initChild`'s prop getters threw `ReferenceError` at hydration (#2231).
+  const innerIndexParam = innerLoop.index || '__innerIdx'
   const comps: InnerLoopComp[] = innerComps.map(comp => ({
     componentName: comp.name,
     selector: buildCompSelector(comp),
@@ -141,7 +146,8 @@ function buildInnerLoopNestedPlan(
     innerContainerSlotId: innerLoop.containerSlotId ?? null,
     innerArrayExpr: innerLoop.array,
     innerParam: innerLoop.param,
-    innerOffsetExpr: buildLoopChildIndexExpr('__innerIdx', innerLoop.offset),
+    innerIndexParam,
+    innerOffsetExpr: buildLoopChildIndexExpr(innerIndexParam, innerLoop.offset),
     innerPreludeStatements: innerLoop.mapPreamble ? [innerLoop.mapPreamble] : [],
     depth: innerLoop.depth,
     comps,
@@ -179,9 +185,14 @@ function buildComponentRootedInnerLoopPlan(
     containerVar: `_${varSlotId(elem.slotId)}`,
     outerArrayExpr: elem.array,
     outerParam: elem.param,
+    // Declared index names only (#2231) — the zip shape never indexes by
+    // position, so there's no synthetic fallback and index-less loops keep
+    // byte-identical output.
+    outerIndexParam: elem.index,
     outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
     innerArrayExpr: innerLoop.array,
     innerParam: innerLoop.param,
+    innerIndexParam: innerLoop.index,
     innerPreludeStatements: innerLoop.mapPreamble ? [innerLoop.mapPreamble] : [],
     depth: innerLoop.depth,
     comps,

package/src/ir-to-client-js/plan/static-array-child-init.ts

@@ -122,7 +122,16 @@ export interface InnerLoopNestedInitPlan {
   innerContainerSlotId: string | null
   innerArrayExpr: string
   innerParam: string
-  /** Inner offset — `__innerIdx` plus any sibling-offset terms. */
+  /**
+   * Inner index parameter identifier — the user's declared `.map((item, i)
+   * => ...)` index name, or the synthetic `__innerIdx` when the callback
+   * declares none (#2231). Emitted as the inner `forEach`'s second param so
+   * prop getters that close over the index resolve it (previously the
+   * synthetic name was hardcoded and a referenced user index threw
+   * `ReferenceError` from `initChild`'s first prop read).
+   */
+  innerIndexParam: string
+  /** Inner offset — `innerIndexParam` plus any sibling-offset terms. */
   innerOffsetExpr: string
   /**
    * Inner `.map()` callback preamble locals, emitted after the
@@ -161,11 +170,21 @@ export interface ComponentRootedInnerLoopInitPlan {
   /** Outer loop's array expression. */
   outerArrayExpr: string
   outerParam: string
+  /**
+   * Outer `.map()` index param name, or `null` when the callback declares
+   * none (#2231). Unlike `inner-loop-nested`, this shape needs no synthetic
+   * fallback — the document-order zip never indexes by position — so the
+   * param is appended to the `forEach` head only when declared, keeping
+   * index-less loops byte-identical.
+   */
+  outerIndexParam: string | null
   /** Outer `.map()` callback preamble locals (#1064). */
   outerPreludeStatements: PreludeStatements
   /** Inner loop's array expression (references the outer param). */
   innerArrayExpr: string
   innerParam: string
+  /** Inner `.map()` index param name, or `null` — see `outerIndexParam` (#2231). */
+  innerIndexParam: string | null
   /** Inner `.map()` callback preamble locals (#1064). */
   innerPreludeStatements: PreludeStatements
   /** Depth used in the leading comment line. */

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

@@ -434,6 +434,12 @@ export function collectLoopChildEventsWithNesting(
             depth: scope.nestingStack.length + 1,
             array: l.array,
             param: l.param,
+            // Event-delegation metadata only (see the field comment on
+            // `NestedLoop.index`) — threaded for type-completeness (#2218)
+            // so this record stays a structurally-valid `NestedLoop`, even
+            // though delegated-handler index binding is handled separately
+            // by `indexBindingLine` in `stringify/event-delegation.ts` (#2189).
+            index: l.index,
             key: l.key,
             markerId: l.markerId,
             containerSlotId: scope.lastElementSlotId,

package/src/ir-to-client-js/stringify/static-array-child-init.ts

@@ -36,7 +36,7 @@
  *     <i>    if (!__outerEl) return
  *     <i>    <outerPreludeStatements*>   // raw outer preamble (#1064)
  *     <i>    const __ic = <innerContainer-or-outerEl>
- *     <i>    <innerArr>.forEach((<innerParam>, __innerIdx) => {
+ *     <i>    <innerArr>.forEach((<innerParam>, <innerIdx>) => {
  *     <i>      const __innerEl = __ic.children[<innerOffset>]
  *     <i>      if (!__innerEl) return
  *     <i>      <innerPreludeStatements*>   // raw inner preamble (#1064)
@@ -137,6 +137,7 @@ function emitInnerLoopNested(lines: string[], plan: InnerLoopNestedInitPlan): vo
     innerContainerSlotId,
     innerArrayExpr,
     innerParam,
+    innerIndexParam,
     innerOffsetExpr,
     innerPreludeStatements,
     depth,
@@ -157,7 +158,7 @@ function emitInnerLoopNested(lines: string[], plan: InnerLoopNestedInitPlan): vo
   } else {
     lines.push(`      const __ic = __outerEl`)
   }
-  lines.push(`      ${innerArrayExpr}.forEach((${innerParam}, __innerIdx) => {`)
+  lines.push(`      ${innerArrayExpr}.forEach((${innerParam}, ${innerIndexParam}) => {`)
   lines.push(`        const __innerEl = __ic.children[${innerOffsetExpr}]`)
   lines.push(`        if (!__innerEl) return`)
   // Inner `.map()` callback preamble — must precede the per-component
@@ -186,9 +187,9 @@ function emitInnerLoopNested(lines: string[], plan: InnerLoopNestedInitPlan): vo
  *   <i>if (<container>) {
  *   <i>  const <scopes_c> = qsaChildScopes(<container>, <selector_c>)   // per comp
  *   <i>  let <cursor_c> = 0
- *   <i>  <outerArr>.forEach((<outerParam>) => {
+ *   <i>  <outerArr>.forEach((<outerParam>[, <outerIdx>]) => {
  *   <i>    <outerPreludeStatements*>
- *   <i>    <innerArr>.forEach((<innerParam>) => {
+ *   <i>    <innerArr>.forEach((<innerParam>[, <innerIdx>]) => {
  *   <i>      <innerPreludeStatements*>
  *   <i>      const <compEl_c> = <scopes_c>[<cursor_c>++]              // per comp
  *   <i>      if (<compEl_c>) initChild('<name>', <compEl_c>, <props>)
@@ -206,9 +207,11 @@ function emitComponentRootedInnerLoop(lines: string[], plan: ComponentRootedInne
     containerVar,
     outerArrayExpr,
     outerParam,
+    outerIndexParam,
     outerPreludeStatements,
     innerArrayExpr,
     innerParam,
+    innerIndexParam,
     innerPreludeStatements,
     depth,
     comps,
@@ -226,11 +229,13 @@ function emitComponentRootedInnerLoop(lines: string[], plan: ComponentRootedInne
     lines.push(`    const ${scopesVar(i)} = qsaChildScopes(${containerVar}, ${comp.selector})`)
     lines.push(`    let ${cursorVar(i)} = 0`)
   })
-  lines.push(`    ${outerArrayExpr}.forEach((${outerParam}) => {`)
+  // Declared index names are appended to the forEach heads (#2231);
+  // index-less loops keep the bare single-param head byte-identical.
+  lines.push(`    ${outerArrayExpr}.forEach((${outerParam}${outerIndexParam ? `, ${outerIndexParam}` : ''}) => {`)
   for (const stmt of outerPreludeStatements) {
     lines.push(`      ${stmt}`)
   }
-  lines.push(`      ${innerArrayExpr}.forEach((${innerParam}) => {`)
+  lines.push(`      ${innerArrayExpr}.forEach((${innerParam}${innerIndexParam ? `, ${innerIndexParam}` : ''}) => {`)
   for (const stmt of innerPreludeStatements) {
     lines.push(`        ${stmt}`)
   }