@barefootjs/jsx 0.5.1 → 0.5.3

package/src/analyzer-context.ts

@@ -20,6 +20,7 @@ import type {
   CompilerError,
   SourceLocation,
   ParamInfo,
+  PropertyInfo,
   ReactiveFactoryInfo,
 } from './types'
 import { type ExcludeRange, collectAllTypeRanges, reconstructWithoutTypes } from './strip-types'
@@ -301,6 +302,46 @@ export function getSourceLocation(
 // Type Helpers
 // =============================================================================
 
+/**
+ * Extract structured {@link PropertyInfo} entries from the members of an object
+ * type literal or interface declaration. Shared so the type-literal branch of
+ * {@link typeNodeToTypeInfo} and interface-definition collection produce
+ * identical field shapes.
+ */
+export function membersToProperties(
+  members: ts.NodeArray<ts.TypeElement>,
+  sourceFile: ts.SourceFile
+): PropertyInfo[] {
+  return members
+    .filter(ts.isPropertySignature)
+    .map((member) => ({
+      name: propertyNameText(member.name, sourceFile),
+      type: typeNodeToTypeInfo(member.type, sourceFile) ?? {
+        kind: 'unknown' as const,
+        raw: 'unknown',
+      },
+      optional: !!member.questionToken,
+      readonly: !!member.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.ReadonlyKeyword
+      ),
+    }))
+}
+
+/**
+ * The source-level name of an object/interface member. String- and numeric-
+ * literal keys are returned unquoted (`{ "id": ... }` → `id`), so consumers see
+ * the same name whether the key was written as an identifier or a string —
+ * `getText()` would otherwise keep the quotes.
+ */
+function propertyNameText(
+  name: ts.PropertyName | undefined,
+  sourceFile: ts.SourceFile
+): string {
+  if (!name) return ''
+  if (ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text
+  return name.getText(sourceFile)
+}
+
 export function typeNodeToTypeInfo(
   typeNode: ts.TypeNode | undefined,
   sourceFile: ts.SourceFile
@@ -352,24 +393,29 @@ export function typeNodeToTypeInfo(
     return {
       kind: 'object',
       raw,
-      properties: typeNode.members
-        .filter(ts.isPropertySignature)
-        .map((member) => ({
-          name: member.name?.getText(sourceFile) ?? '',
-          type: typeNodeToTypeInfo(member.type, sourceFile) ?? {
-            kind: 'unknown',
-            raw: 'unknown',
-          },
-          optional: !!member.questionToken,
-          readonly: !!member.modifiers?.some(
-            (m) => m.kind === ts.SyntaxKind.ReadonlyKeyword
-          ),
-        })),
+      properties: membersToProperties(typeNode.members, sourceFile),
     }
   }
 
   // Type reference (named type)
   if (ts.isTypeReferenceNode(typeNode)) {
+    // Normalise the generic array forms `Array<T>` / `ReadonlyArray<T>` to the
+    // same `kind: 'array'` shape as `T[]`, so every consumer sees one array
+    // representation regardless of how the source spelled it.
+    const refName = ts.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : ''
+    if (
+      (refName === 'Array' || refName === 'ReadonlyArray') &&
+      typeNode.typeArguments?.length === 1
+    ) {
+      return {
+        kind: 'array',
+        raw,
+        elementType: typeNodeToTypeInfo(typeNode.typeArguments[0], sourceFile) ?? {
+          kind: 'unknown',
+          raw: 'unknown',
+        },
+      }
+    }
     return {
       kind: 'interface',
       raw,

package/src/analyzer.ts

@@ -16,6 +16,7 @@ import {
   createAnalyzerContext,
   getSourceLocation,
   typeNodeToTypeInfo,
+  membersToProperties,
   isComponentFunction,
   isArrowComponentFunction,
 } from './analyzer-context'
@@ -1782,6 +1783,7 @@ function collectInterfaceDefinition(
     kind: 'interface',
     name: node.name.text,
     definition: node.getText(ctx.sourceFile),
+    properties: membersToProperties(node.members, ctx.sourceFile),
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
   })
 }
@@ -1790,10 +1792,16 @@ function collectTypeAliasDefinition(
   node: ts.TypeAliasDeclaration,
   ctx: AnalyzerContext
 ): void {
+  // Only object-type aliases carry structured fields; other aliases
+  // (string-literal unions, etc.) have no field set to record.
+  const properties = ts.isTypeLiteralNode(node.type)
+    ? membersToProperties(node.type.members, ctx.sourceFile)
+    : undefined
   ctx.typeDefinitions.push({
     kind: 'type',
     name: node.name.text,
     definition: node.getText(ctx.sourceFile),
+    properties,
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
   })
 }

package/src/combine-client-js.ts

@@ -8,6 +8,8 @@
  * into the parent's file, eliminating the need for separate HTTP requests.
  */
 
+import ts from 'typescript'
+
 const CHILD_PLACEHOLDER_RE = /import '\/\* @bf-child:(\w+) \*\/'/g
 
 /**
@@ -101,33 +103,75 @@ function parseAndMerge(
   otherImports: string[],
   codeSections: string[]
 ): void {
-  const codeLines: string[] = []
-
-  for (const line of content.split('\n')) {
-    if (line.startsWith('import ')) {
-      if (line.includes('@bf-child:')) continue
-
-      const match = line.match(/^import \{ ([^}]+) \} from ['"]([^'"]+)['"]/)
-      if (match) {
-        const names = match[1].split(',').map(n => n.trim())
-        const source = match[2]
-        if (!importsBySource.has(source)) {
-          importsBySource.set(source, new Set())
-        }
-        for (const name of names) {
-          importsBySource.get(source)!.add(name)
-        }
-      } else {
-        if (!otherImports.includes(line)) {
-          otherImports.push(line)
-        }
+  // Parse the client JS so we only ever treat *real* top-level
+  // `ImportDeclaration` statements as imports. The predecessor matched
+  // raw lines beginning with `import `, which also caught `import …`
+  // lines that merely live *inside a string / template literal value*
+  // (e.g. a data module exporting a code snippet). Tearing such a line
+  // out of its string relocated the component's real runtime import into
+  // the literal and left `hydrate` undefined at call time. See
+  // piconic-ai/barefootjs#1702.
+  // Parent pointers aren't needed here — we only read `statements` and each
+  // import's `getStart`/`getEnd` — so skip building them to keep the per-chunk
+  // parse cheap when combining many files.
+  const sourceFile = ts.createSourceFile(
+    'combine.js',
+    content,
+    ts.ScriptTarget.Latest,
+    /*setParentNodes*/ false,
+    ts.ScriptKind.JS,
+  )
+
+  // Character spans of the top-level imports to strip from the emitted
+  // code, so everything that isn't an import (including literals whose
+  // contents look like imports) is preserved verbatim.
+  const importSpans: Array<[number, number]> = []
+
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isImportDeclaration(stmt)) continue
+    const start = stmt.getStart(sourceFile)
+    const end = stmt.getEnd()
+    importSpans.push([start, end])
+
+    const stmtText = content.slice(start, end)
+    // `@bf-child:` placeholders are resolved by inlining elsewhere; drop
+    // them entirely (neither merged nor kept as code).
+    if (stmtText.includes('@bf-child:')) continue
+
+    const clause = stmt.importClause
+    const bindings = clause?.namedBindings
+    const specifier = ts.isStringLiteral(stmt.moduleSpecifier)
+      ? stmt.moduleSpecifier.text
+      : ''
+    if (clause && !clause.name && bindings && ts.isNamedImports(bindings)) {
+      // Pure named import (`import { a, b as c } from '…'`) — merge by source.
+      if (!importsBySource.has(specifier)) {
+        importsBySource.set(specifier, new Set())
+      }
+      const set = importsBySource.get(specifier)!
+      for (const el of bindings.elements) {
+        const name = el.propertyName
+          ? `${el.propertyName.text} as ${el.name.text}`
+          : el.name.text
+        set.add(name)
       }
     } else {
-      codeLines.push(line)
+      // default / namespace / side-effect import — keep verbatim.
+      if (!otherImports.includes(stmtText)) {
+        otherImports.push(stmtText)
+      }
     }
   }
 
-  const code = codeLines.join('\n').trim()
+  // Reconstruct the code with the import spans removed.
+  let code = ''
+  let cursor = 0
+  for (const [start, end] of importSpans) {
+    code += content.slice(cursor, start)
+    cursor = end
+  }
+  code += content.slice(cursor)
+  code = code.trim()
   if (code) {
     codeSections.push(code)
   }

package/src/expression-parser.ts

@@ -214,6 +214,21 @@ const UNSUPPORTED_METHODS = new Set([
   // `bf_lower` / `bf_upper` (Go) and Perl's native `lc` / `uc` (Mojo).
   // `trim` lowers via the `array-method` IR + `bf_trim` (Go) and a
   // Perl regex strip (Mojo).
+  //
+  // #1448 follow-up — String methods that have NO lowering yet. These
+  // were previously absent from this gate, so `isSupported` reported
+  // them "supported" and the adapters emitted a raw method call
+  // (`{{.Name.StartsWith "a"}}` on Go, `$name->{startsWith}('a')` on
+  // Mojo) with no build diagnostic — a silent footgun that only
+  // surfaced as a crash at template-render time. Listing them here
+  // makes the build fail loudly with BF101 (the same treatment the
+  // unsupported array methods above get), pointing users at the
+  // `/* @client */` escape hatch. Each name drops off as its lowering
+  // lands. See #1448 "Unsupported string methods" Tier B / Tier C.
+  'split', 'startsWith', 'endsWith', 'replace', 'replaceAll',
+  'repeat', 'padStart', 'padEnd',
+  'charAt', 'charCodeAt', 'codePointAt', 'normalize',
+  'substring', 'substr', 'match', 'matchAll', 'search',
 ])
 
 // =============================================================================
@@ -1724,7 +1739,7 @@ function checkSupport(expr: ParsedExpr): SupportResult {
           return {
             supported: false,
             level: 'L5_UNSUPPORTED',
-            reason: `Higher-order method '${methodName}()' requires client-side evaluation. Use @client directive or pre-compute in Go.`,
+            reason: `Method '${methodName}()' has no template lowering and requires client-side evaluation. Wrap the expression in /* @client */ to defer it to hydration, or pre-compute the value before rendering.`,
           }
         }
       }

package/src/index.ts

@@ -40,7 +40,9 @@ export type {
   IRTemplatePart,
   IRProp,
   ParamInfo,
+  PropertyInfo,
   TypeInfo,
+  TypeDefinition,
   SourceLocation,
   CompilerError,
 } from './types'

package/src/ir-to-client-js/collect-elements.ts

@@ -3,52 +3,209 @@
  */
 
 import { type IRNode, type IRElement, type IRComponent, type IRLoop, type IRProp, pickAttrMetaFromIR } from '../types'
-import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, NestedLoop } from './types'
+import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, LoopOffset, NestedLoop } from './types'
 import { attrValueToString, freeIdsFromRefs, quotePropName, PROPS_PARAM } from './utils'
 import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings } from './reactivity'
 import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr } from './html-template'
 import { expandDynamicPropValue, expandConstantForReactivity } from './prop-handling'
 import { walkIR, stopAt } from './walker'
+import { buildLoopChainExpr } from '../loop-chain'
 
-/** Check if an IR node produces a DOM child element (for sibling offset counting). */
-function producesDomChild(node: IRNode): boolean {
+/** Expressions that render nothing (0 DOM nodes) — `&&` / `?:` empty branches. */
+const EMPTY_RENDER_EXPRS = new Set(['null', 'undefined', 'false', "''", '""', '``'])
+
+/**
+ * Number of *element* children a node contributes to its parent's `.children`
+ * run — the collection that `container.children[idx]` indexes and that event
+ * delegation's `Array.from(container.children).indexOf(...)` walks. `.children`
+ * is element-only, so text / comment nodes never count.
+ *
+ * Returns a folded integer when the count is statically known, a JS expression
+ * string when it depends on runtime state, or `null` when the element count is
+ * statically undecidable (the caller then falls back to the legacy count):
+ *   - element / component / provider / async → `1` (one root element)
+ *   - text / empty-render expression (`null`/`false`/…) → `0`
+ *   - plain loop → `(arr).length`; per-item-conditional / flatMap loop → `null`
+ *     (renders a runtime-variable count, not `array.length`) (#1693)
+ *   - conditional → fold to a number when both branches match, else
+ *     `(cond ? t : f)`; `null` when a branch is undecidable (e.g. the `??`/`||`
+ *     left operand, a bare expression that may render an element OR text)
+ *   - fragment → sum of its children (transparent wrapper)
+ *   - bare expression / slot / everything else → `null` (undecidable)
+ */
+function domElementCount(node: IRNode): number | string | null {
+  switch (node.type) {
+    case 'element':
+    case 'component':
+    case 'provider':
+    case 'async':
+      return 1
+    case 'text':
+      return 0
+    case 'expression':
+      // `&&` / `?:` empty branches (`null`, `false`, …) render nothing; any
+      // other expression may resolve to an element or to text — undecidable.
+      return EMPTY_RENDER_EXPRS.has(node.expr.trim()) ? 0 : null
+    case 'loop':
+      // A per-item-conditional body (#1665) or flatMap renders a
+      // runtime-variable element count per item, not `array.length`.
+      if (node.bodyIsItemConditional || node.method === 'flatMap') return null
+      return `(${buildLoopChainExpr({
+        base: node.array,
+        sortComparator: node.sortComparator,
+        filterPredicate: node.filterPredicate,
+        chainOrder: node.chainOrder,
+      })}).length`
+    case 'conditional': {
+      const t = domElementCount(node.whenTrue)
+      const f = domElementCount(node.whenFalse)
+      if (t === null || f === null) return null
+      if (typeof t === 'number' && typeof f === 'number' && t === f) return t
+      // Active branch chosen at runtime — reuse the raw `condition`, the exact
+      // form `insert()` evaluates in the same init scope.
+      return `(${node.condition} ? ${t} : ${f})`
+    }
+    case 'fragment':
+      return sumElementCounts(node.children)
+    default:
+      // slot / if-statement: element count not statically known.
+      return null
+  }
+}
+
+/**
+ * Sum `domElementCount` over a run of nodes, folding the static part. Returns
+ * `null` if any child's count is undecidable — the whole run is then unknown.
+ */
+function sumElementCounts(nodes: readonly IRNode[]): number | string | null {
+  let staticCount = 0
+  const dynamic: string[] = []
+  for (const n of nodes) {
+    const c = domElementCount(n)
+    if (c === null) return null
+    if (typeof c === 'number') staticCount += c
+    else dynamic.push(c)
+  }
+  if (dynamic.length === 0) return staticCount
+  const parts = staticCount > 0 ? [String(staticCount), ...dynamic] : dynamic
+  return parts.length === 1 ? parts[0] : `(${parts.join(' + ')})`
+}
+
+/**
+ * Pre-#1693 element-count heuristic, used as the fallback for nodes whose count
+ * `domElementCount` cannot decide. Mirrors the old `producesDomChild` exactly,
+ * so an undecidable sibling contributes precisely what it did before this fix —
+ * guaranteeing no regression on shapes the new counting can't improve (a bare
+ * expression, a `??`/`||` fallback, a per-item-conditional loop).
+ */
+function legacyElementCount(node: IRNode): number {
   return node.type === 'element' || node.type === 'component' || node.type === 'provider'
     || node.type === 'async'
     || node.type === 'text' || (node.type === 'expression' && !node.reactive)
     || node.type === 'conditional'
+    ? 1
+    : 0
 }
 
 /**
- * Pre-pass: for every loop node in the IR tree, record the number of non-loop
- * DOM siblings that appear before it in its parent element. Read when
- * constructing TopLevelLoop and NestedLoop so the client JS can offset
- * children[idx] access past statically-rendered siblings.
+ * Pre-pass: for every loop node in the IR tree, record the sibling nodes that
+ * appear before it in its parent container. Read when constructing
+ * TopLevelLoop and NestedLoop so the client JS can offset children[idx]
+ * access past everything rendered ahead of the loop's items.
+ *
+ * Counting must happen for every container whose children render as a
+ * contiguous run of DOM siblings into the same parent — not just `element`.
+ * A loop nested directly inside a component (`<Wrapper><span/>{xs.map(...)}`
+ * </Wrapper>`), fragment, provider, or async boundary has its preceding
+ * siblings rendered as siblings of the loop's items too, so `children[idx]`
+ * access is shifted exactly as it is under an element parent (#1688).
+ *
+ * Transparent containers (fragment / provider / async) render no DOM element
+ * wrapper, so their children are siblings in the nearest ancestor element —
+ * not in a container of their own. `recordRun` therefore threads ONE
+ * preceding-sibling accumulator through them, so a loop inside a fragment sees
+ * the parent element's earlier siblings too, not just the fragment's own
+ * children (#1699). `<Box><hr/><hr/><>{xs.map(...)}</></Box>` must offset the
+ * items past both `<hr/>`s.
+ *
+ * The siblings are stored raw; `resolveLoopOffset` turns each into its element
+ * count via `domElementCount`. That generalisation closes the #1688 follow-up
+ * (#1693): a preceding `.map()` contributes `array.length` and a preceding
+ * conditional contributes a `(cond ? … : …)` term, both resolved at runtime —
+ * a static-only count resolved later groups' nested children against the wrong
+ * `children[idx]`, leaving them inert after hydration.
  *
  * Computed once up front (instead of during collection) so the offset data
  * lives in an explicit value rather than a module-level WeakMap mutated by
  * two separate traversals.
  */
-export function computeLoopSiblingOffsets(root: IRNode): Map<IRLoop, number> {
-  const offsets = new Map<IRLoop, number>()
-  walkIR(root, null, {
-    element: ({ node: el, descend }) => {
-      let nonLoopCount = 0
-      for (const child of el.children) {
-        if (child.type === 'loop') {
-          if (nonLoopCount > 0) offsets.set(child, nonLoopCount)
-        } else if (producesDomChild(child)) {
-          nonLoopCount++
+export function computeLoopSiblingOffsets(root: IRNode): Map<IRLoop, IRNode[]> {
+  const offsets = new Map<IRLoop, IRNode[]>()
+  // Walk a flat DOM run, flattening transparent containers inline so their
+  // children join the same preceding-sibling accumulator.
+  const recordRun = (children: IRNode[], preceding: IRNode[]): void => {
+    for (const child of children) {
+      if (child.type === 'loop') {
+        // Record the preceding run only when something precedes this loop (a
+        // leading loop keeps bare `children[idx]`). `!offsets.has`: the
+        // enclosing run records the loop first, in pre-order, with the full
+        // preceding context; a later standalone visit of the transparent
+        // wrapper (still descended for loops that sit *directly* in a root /
+        // loop-body / branch fragment) must not overwrite it with a shorter
+        // run.
+        if (preceding.length > 0 && !offsets.has(child)) {
+          offsets.set(child, [...preceding])
         }
+        preceding.push(child)
+      } else if (child.type === 'fragment' || child.type === 'provider' || child.type === 'async') {
+        // Transparent: no element wrapper — its children render into this run.
+        recordRun(child.children, preceding)
+      } else {
+        preceding.push(child)
       }
-      descend()
-    },
-    // All container kinds (fragment / component / provider / async / loop /
-    // conditional / if-statement) rely on walkIR's default descent with the
-    // same scope. Leaves (text / expression / slot) are no-ops.
+    }
+  }
+  const containerVisit = ({ node, descend }: { node: { children: IRNode[] }; descend: () => void }): void => {
+    recordRun(node.children, [])
+    descend()
+  }
+  walkIR(root, null, {
+    element: containerVisit,
+    component: containerVisit,
+    fragment: containerVisit,
+    provider: containerVisit,
+    async: containerVisit,
+    // `loop` / `conditional` / `if-statement` are not flat sibling
+    // containers (their children are item bodies / branches), and leaves
+    // (text / expression / slot) have no children — all rely on walkIR's
+    // default descent with the same scope.
   })
   return offsets
 }
 
+/**
+ * Resolve a loop's preceding-sibling run into the `LoopOffset` value object
+ * stored on `TopLevelLoop` / `NestedLoop`: the folded static element count
+ * plus one dynamic term (`(arr).length`, `(cond ? … : …)`) per sibling whose
+ * count is only known at runtime. Siblings whose count is statically
+ * undecidable fall back to `legacyElementCount` (the pre-#1693 behaviour).
+ * Returns `undefined` when nothing precedes the loop (or only non-element
+ * nodes do), so the loop keeps bare `children[idx]`.
+ */
+function resolveLoopOffset(preceding: IRNode[] | undefined): LoopOffset | undefined {
+  if (!preceding || preceding.length === 0) return undefined
+  let staticCount = 0
+  const dynamicTerms: string[] = []
+  for (const node of preceding) {
+    const c = domElementCount(node)
+    if (c === null) staticCount += legacyElementCount(node)
+    else if (typeof c === 'number') staticCount += c
+    else dynamicTerms.push(c)
+  }
+  if (staticCount === 0 && dynamicTerms.length === 0) return undefined
+  return { staticCount, dynamicTerms }
+}
+
 /**
  * Options controlling `collectInnerLoops` traversal and payload collection.
  *
@@ -110,7 +267,7 @@ export const branchInnerLoopOptions: CollectInnerLoopsOptions = {
  */
 export function collectInnerLoops(
   nodes: IRNode[],
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
   outerLoopParam?: string,
   ctx?: ClientJsContext,
   options?: CollectInnerLoopsOptions,
@@ -239,7 +396,7 @@ export function collectInnerLoops(
           refsOuterParam: refsOuter,
           childComponents,
           insideConditional: !flat && scope.insideCond ? true : undefined,
-          siblingOffset: flat ? undefined : (siblingOffsets.get(n) || undefined),
+          offset: flat ? undefined : resolveLoopOffset(siblingOffsets.get(n)),
           bindings,
         })
         // Branch-mode callers handle deeper nesting via their own collection paths.
@@ -267,7 +424,7 @@ export function collectInnerLoops(
  */
 function decideLoopRendering(
   loop: IRLoop,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
   ctx: ClientJsContext | undefined,
 ): { useElementReconciliation: boolean; innerLoops: NestedLoop[] | undefined } {
   const hasNestedComps = (loop.nestedComponents?.length ?? 0) > 0
@@ -421,7 +578,7 @@ function buildBranchChildComponents(
 export function collectElements(
   node: IRNode,
   ctx: ClientJsContext,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
   insideConditional = false,
 ): void {
   walkIR<boolean>(node, insideConditional, {
@@ -576,7 +733,7 @@ export function collectElements(
         isStaticArray: l.isStaticArray,
         useElementReconciliation,
         innerLoops: (useElementReconciliation || (l.isStaticArray && innerLoops?.length)) ? innerLoops : undefined,
-        siblingOffset: siblingOffsets.get(l) || undefined,
+        offset: resolveLoopOffset(siblingOffsets.get(l)),
         filterPredicate: l.filterPredicate ? {
           param: l.filterPredicate.param,
           raw: l.filterPredicate.raw,
@@ -835,7 +992,7 @@ function collectBranchTextEffects(node: IRNode): ConditionalBranchTextEffect[] {
 function collectBranchLoops(
   node: IRNode,
   ctx: ClientJsContext | undefined,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
 ): BranchLoop[] {
   const loops: BranchLoop[] = []
   const restNames = ctx ? buildRestSpreadNames(ctx) : undefined
@@ -934,7 +1091,7 @@ function collectBranchLoops(
 function buildConditionalMetadata(
   node: IRNode & { type: 'conditional' },
   ctx: ClientJsContext,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
 ): ConditionalElement {
   const restNames = buildRestSpreadNames(ctx)
   // Use loopDepth=-1 so the first loop encountered inside the branch emits
@@ -964,7 +1121,7 @@ function buildConditionalMetadata(
 function summarizeBranch(
   node: IRNode,
   ctx: ClientJsContext,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
 ): import('./types').BranchSummary {
   return {
     events: collectConditionalBranchEvents(node),
@@ -984,7 +1141,7 @@ function summarizeBranch(
 function collectBranchConditionals(
   node: IRNode,
   ctx: ClientJsContext,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
 ): ConditionalElement[] {
   const result: ConditionalElement[] = []
   walkIR(node, null, {
@@ -1032,7 +1189,7 @@ function collectBranchConditionals(
 export function collectLoopChildBindings(
   children: readonly IRNode[],
   ctx: ClientJsContext,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
   loopParam: string,
   loopParamBindings: readonly import('../types').LoopParamBinding[] | undefined,
 ): LoopChildBindings {
@@ -1050,7 +1207,7 @@ export function collectLoopChildBindings(
 export function collectLoopChildConditionals(
   node: IRNode,
   ctx: ClientJsContext,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
   loopParam?: string,
   loopParamBindings?: readonly import('../types').LoopParamBinding[],
 ): LoopChildConditional[] {
@@ -1125,7 +1282,7 @@ export function collectLoopChildConditionals(
 function summarizeLoopChildBranch(
   node: IRNode,
   ctx: ClientJsContext,
-  siblingOffsets: Map<IRLoop, number>,
+  siblingOffsets: Map<IRLoop, IRNode[]>,
   loopParam?: string,
   loopParamBindings?: readonly import('../types').LoopParamBinding[],
 ): LoopChildBranchSummary {

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

@@ -69,7 +69,7 @@ export function buildStaticArrayDelegationPlan(elem: TopLevelLoop): EventDelegat
       arrayExpr: buildChainedArrayExpr(elem),
       param: elem.param,
       mapPreamble: elem.mapPreamble ?? null,
-      siblingOffset: elem.siblingOffset ?? null,
+      offset: elem.offset ?? null,
     },
   }
 }

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

@@ -25,6 +25,7 @@ import type {
 } from '../../types'
 import {
   buildChainedArrayExpr,
+  buildLoopChildIndexExpr,
   setIntersects,
   varSlotId,
   wrapLoopParamAsAccessor,
@@ -129,7 +130,7 @@ export function buildStaticLoopPlan(elem: TopLevelLoop, unsafeLocalNames: Set<st
   }
 
   const indexParam = elem.index || '__idx'
-  const childIndexExpr = elem.siblingOffset ? `${indexParam} + ${elem.siblingOffset}` : indexParam
+  const childIndexExpr = buildLoopChildIndexExpr(indexParam, elem.offset)
 
   return {
     kind: 'static',

package/src/ir-to-client-js/control-flow/plan/event-delegation.ts

@@ -5,7 +5,7 @@
  * container variable and the per-event item-lookup strategy.
  */
 
-import type { LoopChildEvent, TopLevelLoop } from '../../types'
+import type { LoopChildEvent, LoopOffset, TopLevelLoop } from '../../types'
 
 /**
  * Plan for a loop's event-delegation block. Covers three legacy emitters:
@@ -72,6 +72,11 @@ export interface StaticIndexItemLookup {
   arrayExpr: string
   param: string
   mapPreamble: string | null
-  /** Sibling offset for `__idx` arithmetic; `null` when no offset. */
-  siblingOffset: number | null
+  /**
+   * Offset of the loop's items past its preceding container siblings. Its
+   * terms are subtracted from the DOM child index to recover the array index,
+   * so later `static + .map()` groups resolve the correct item (#1693).
+   * `null` when nothing precedes the loop.
+   */
+  offset: LoopOffset | null
 }