@barefootjs/jsx 0.18.4 → 0.18.7

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

@@ -10,7 +10,7 @@ import { nameForRegistryRef } from './component-scope.ts'
 import { assertNever } from './walker.ts'
 import { buildSignalMemoEnv, csrSubstitute, applyPropsRewrite, type CsrEnv } from './csr-substitute.ts'
 import type { ClientJsContext } from './types.ts'
-import { BF_PARENT_SCOPE_PLACEHOLDER, BF_SCOPE } from '@barefootjs/shared'
+import { BF_PARENT_SCOPE_PLACEHOLDER, BF_SCOPE, escapeHtml } from '@barefootjs/shared'
 import { buildLoopChainExpr } from '../loop-chain.ts'
 
 /**
@@ -145,6 +145,42 @@ function applyIterationShape(
       callbackParam: `(${node.param})`,
     }
   }
+  // `objectIteration` (#2168 object-entries-map): reconstruct the STATIC
+  // `Object.entries/keys/values(x)` call the compiler stripped at IR-build
+  // time (`isObjectIteratorCall`, `jsx-to-ir.ts`) — `arrayExpr` here is just
+  // `x` (the plain object), so the client, unlike a template adapter,
+  // re-wraps it in real JS to get the actual entries/keys/values array
+  // (this runs in a real JS engine, so no per-language lowering is needed).
+  //
+  // Unlike the array `iterationShape` case, the 'entries' ARRAY wrap does
+  // NOT require `node.index` — that field is only populated for a CLEAN
+  // 2-identifier destructure (`([word, n]) => …`); an elided/nested
+  // pattern (`([, cfg]) => …`) falls through to the generic `paramBindings`
+  // machinery instead (`node.param` stays the raw destructure TEXT, e.g.
+  // `"[, cfg]"`, which is already a syntactically valid callback param that
+  // correctly destructures a `[key, value]` pair — see the trailing
+  // fallback below). Only the ARRAY needs wrapping in that case; the
+  // callback param is unaffected either way.
+  if (node.objectIteration === 'entries') {
+    return {
+      array: `Object.entries(${arrayExpr})`,
+      callbackParam: node.index
+        ? `([${node.index}, ${node.param}])`
+        : `(${node.param}${indexParam})`,
+    }
+  }
+  if (node.objectIteration === 'keys') {
+    return {
+      array: `Object.keys(${arrayExpr})`,
+      callbackParam: `(${node.param})`,
+    }
+  }
+  if (node.objectIteration === 'values') {
+    return {
+      array: `Object.values(${arrayExpr})`,
+      callbackParam: `(${node.param})`,
+    }
+  }
   return { array: arrayExpr, callbackParam: `(${node.param}${indexParam})` }
 }
 
@@ -313,7 +349,7 @@ function renderTemplateAttrPart(
     case 'boolean-attr':
       return attrName
     case 'literal':
-      return `${attrName}="${v.value}"`
+      return `${attrName}="${escapeHtml(v.value)}"`
     case 'expression': {
       const valExpr = wrap(v.expr)
       return templateAttrExpr(attrName, valExpr, v.presenceOrUndefined)
@@ -550,7 +586,9 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -757,7 +795,7 @@ export function buildLoopSkeletonTemplate(node: IRNode, safe: LoopSkeletonSafeSl
         const v = a.value
         switch (v.kind) {
           case 'literal':
-            attrParts.push(`${toHtmlAttrName(a.name)}="${v.value}"`)
+            attrParts.push(`${toHtmlAttrName(a.name)}="${escapeHtml(v.value)}"`)
             break
           case 'boolean-attr':
             attrParts.push(toHtmlAttrName(a.name))
@@ -796,7 +834,9 @@ export function buildLoopSkeletonTemplate(node: IRNode, safe: LoopSkeletonSafeSl
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -835,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
@@ -870,7 +1100,9 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -1093,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
   /**
@@ -1228,7 +1474,7 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
                 return templateAttrExpr(keyName, transformExpr(tmplStr))
               }
               case 'literal':
-                return `${keyName}="${v.value}"`
+                return `${keyName}="${escapeHtml(v.value)}"`
               default:
                 return ''
             }
@@ -1238,7 +1484,7 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
             case 'boolean-attr':
               return attrName
             case 'literal':
-              return `${attrName}="${v.value}"`
+              return `${attrName}="${escapeHtml(v.value)}"`
             case 'expression':
               return templateAttrExpr(attrName, transformExpr(v.expr, v.templateExpr), v.presenceOrUndefined)
             case 'template': {
@@ -1269,7 +1515,9 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -1806,7 +2054,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
             case 'boolean-attr':
               return attrName
             case 'literal':
-              return `${attrName}="${v.value}"`
+              return `${attrName}="${escapeHtml(v.value)}"`
             case 'expression':
               return templateAttrExpr(attrName, transformExpr(v.expr, v.templateExpr), v.presenceOrUndefined)
             case 'template': {
@@ -1837,7 +2085,9 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -1942,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.
@@ -1976,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/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}`)
   }

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

@@ -22,6 +22,7 @@ import type {
   ImportInfo,
 } from '../types.ts'
 import type { CsrInlinabilityMap } from './csr-substitute.ts'
+import type { SkeletonSlotPaths } from './html-template.ts'
 
 export interface ClientJsContext {
   componentName: string
@@ -283,6 +284,16 @@ export interface LoopCore {
    * (#1448 Tier B). Threaded from `IRLoop.iterationShape`.
    */
   iterationShape?: 'entries' | 'keys'
+
+  /**
+   * Object iteration shape from the STATIC `Object.entries(x)` /
+   * `.keys(x)` / `.values(x)` call form (#2168 object-entries-map) —
+   * distinct from {@link iterationShape} for the same reason `IRLoop`'s
+   * own field is (see that field's docstring, `packages/jsx/src/types.ts`):
+   * `x` is a plain object, not an array. Threaded from
+   * `IRLoop.objectIteration`.
+   */
+  objectIteration?: 'entries' | 'keys' | 'values'
 }
 
 /**
@@ -394,6 +405,18 @@ export type ConditionalBranchConditional = ConditionalElement
 export interface NestedLoop extends LoopCore {
   kind: 'nested'
   depth: number    // 1 for first nesting level, 2 for second, etc.
+  /**
+   * Index parameter of the inner `.map()` callback (e.g. `i` from
+   * `.map((item, i) => ...)`), or `null` when the callback doesn't declare
+   * one. Mirrors `TopLevelLoop.index` / `BranchLoop.index` — added by #2218
+   * so a nested loop's `key`/reactive-text/reactive-attr/template/event/ref
+   * expressions that reference the index can be bound instead of throwing
+   * `ReferenceError` at runtime. The renderItem body only receives the
+   * index as a synthetic `__innerIdx<uid>` positional param (to avoid
+   * cross-depth name collisions), so emitters must alias it under this
+   * name when referenced — see `nestedLoopReferencesIndex` in `shared.ts`.
+   */
+  index: string | null
   containerSlotId: string | null // Slot ID of the parent element containing the loop (for hydration)
   /** HTML template for a single inner loop item (for mapArray CSR rendering) */
   template?: string
@@ -519,6 +542,14 @@ export interface TopLevelLoop extends LoopCore {
    * proven covered by an effect).
    */
   skeletonTemplate?: string
+  /**
+   * Compile-time child-index paths for `skeletonTemplate`'s dynamic slots
+   * (perf, #2143), computed by `computeSkeletonSlotPaths` from the same IR
+   * tree. `undefined` means "resolve every slot via `qsa`/`$t` at runtime"
+   * (skeletonTemplate is still hoisted/cloned — only the runtime lookups on
+   * top of the fresh clone become the fallback rather than the path chain).
+   */
+  skeletonPaths?: SkeletonSlotPaths
   childEventHandlers: string[] // Bare-identifier event handler names (for the reachability graph)
   childComponent?: IRLoopChildComponent // For createComponent-based rendering
   nestedComponents?: IRLoopChildComponent[] // For nested components in loop bodies