@barefootjs/jsx 0.5.2 → 0.6.0

package/src/expression-parser.ts

@@ -46,6 +46,13 @@ export type ParsedExpr =
         | 'toLowerCase'
         | 'toUpperCase'
         | 'trim'
+        | 'split'
+        | 'startsWith'
+        | 'endsWith'
+        | 'replace'
+        | 'repeat'
+        | 'padStart'
+        | 'padEnd'
       object: ParsedExpr
       args: ParsedExpr[]
     }
@@ -225,12 +232,46 @@ const UNSUPPORTED_METHODS = new Set([
   // 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',
+  // `split` is no longer here — `String.prototype.split(sep)` lowers
+  // via the `array-method` IR + `bf_split` (Go) / `bf->split` (Mojo),
+  // returning an array that composes with `.join()` / `.map()` / etc.
+  // See #1448 Tier B.
+  // `startsWith` / `endsWith` are no longer here — both lower via the
+  // `array-method` IR + `bf_starts_with` / `bf_ends_with` (Go) and
+  // `bf->starts_with` / `bf->ends_with` (Mojo). See #1448 Tier B.
+  // `replace` is no longer here — the string-pattern form lowers via
+  // the `array-method` IR + `bf_replace` (Go) / `bf->replace` (Mojo);
+  // the regex-pattern form is refused at the parse arm below (it would
+  // need the per-adapter regex-flavour decision). `replaceAll` stays
+  // refused. See #1448 Tier B.
+  // `repeat` is no longer here — `String.prototype.repeat(n)` lowers via
+  // the `array-method` IR + `bf_repeat` (Go) / `bf->repeat` (Mojo).
+  // See #1448 Tier B.
+  // `padStart` / `padEnd` are no longer here — both lower via the
+  // `array-method` IR + `bf_pad_start` / `bf_pad_end` (Go) and
+  // `bf->pad_start` / `bf->pad_end` (Mojo). See #1448 Tier B.
+  'replaceAll',
   'charAt', 'charCodeAt', 'codePointAt', 'normalize',
   'substring', 'substr', 'match', 'matchAll', 'search',
 ])
 
+// Methods that lower at their single-argument form but whose EXTRA
+// argument is meaningful and NOT yet lowered: the `fromIndex` of
+// `.includes` / `.indexOf` / `.lastIndexOf` (the 2-arg form) and the
+// additional arrays of a variadic `.concat(a, b, …)`. The relaxed
+// per-method arms in `convertNode` accept every method's zero-arg
+// defaults (`.join()` / `.slice()` / `.concat()` / `.at()`) and
+// JS-ignored trailing arguments; this guard catches only the remaining
+// meaningful-extra forms, refusing them with BF101 because silently
+// dropping the argument would make the SSR output differ from the
+// client. See #1448.
+const LOWERED_ARRAY_METHODS = new Set([
+  'includes',
+  'indexOf',
+  'lastIndexOf',
+  'concat',
+])
+
 // =============================================================================
 // Expression Parser
 // =============================================================================
@@ -344,7 +385,10 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
     // etc. later means widening the IR discriminator, not adding more
     // branches to every adapter's call dispatch.
     if (callee.kind === 'member' && !callee.computed) {
-      if (callee.property === 'join' && args.length === 1) {
+      // `.join()` / `.join(sep)` — JS defaults the separator to `,` when
+      // omitted and ignores any extra arguments. Accept every arity; the
+      // adapters supply the default separator and read only `args[0]`.
+      if (callee.property === 'join') {
         return { kind: 'array-method', method: 'join', object: callee.object, args }
       }
       // `.includes(x)` — shared between `Array.prototype.includes` and
@@ -369,20 +413,28 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       // element). Go has `bf_at` registered already (see runtime
       // FuncMap); Mojo's `bf->at` wraps the same arithmetic.
       // See #1448 Tier A.
-      if (callee.property === 'at' && args.length === 1) {
+      // `.at(i)` — JS ignores any argument past the first, and `.at()`
+      // with no argument is `.at(0)` (the first element). Accept every
+      // arity; the adapters read `args[0]` (defaulting the index to 0).
+      if (callee.property === 'at') {
         return { kind: 'array-method', method: 'at', object: callee.object, args }
       }
-      // `.concat(other)` — merges two arrays in order. Go uses
-      // `bf_concat` (reflect-based append into `[]any`); Mojo uses
-      // `bf->concat` (Perl list builder). Variadic shapes (`.concat(a, b)`)
-      // are out of scope for this PR — gated to single-arg here.
-      if (callee.property === 'concat' && args.length === 1) {
+      // `.concat()` / `.concat(other)` — `.concat()` returns a shallow
+      // copy (indistinguishable from the receiver in an SSR snapshot),
+      // and `.concat(other)` merges the two arrays. Go uses `bf_concat`
+      // (reflect-based append into `[]any`); Mojo uses `bf->concat`
+      // (Perl list builder). The VARIADIC form (`.concat(a, b, …)`) is
+      // not lowered yet — it's refused by the guard below rather than
+      // silently dropping the extra arrays.
+      if (callee.property === 'concat' && args.length <= 1) {
         return { kind: 'array-method', method: 'concat', object: callee.object, args }
       }
-      // `.slice(start)` / `.slice(start, end)` — both forms route
-      // through `bf_slice` (Go) / `bf->slice` (Mojo); the helpers
-      // treat a missing / undef `end` as "to length".
-      if (callee.property === 'slice' && (args.length === 1 || args.length === 2)) {
+      // `.slice()` / `.slice(start)` / `.slice(start, end)` — route
+      // through `bf_slice` (Go) / `bf->slice` (Mojo). A missing `start`
+      // defaults to 0 (full copy), a missing / undef `end` means "to
+      // length", and JS ignores any third+ argument. Accept every arity;
+      // the adapters read only `args[0]` / `args[1]`.
+      if (callee.property === 'slice') {
         return { kind: 'array-method', method: 'slice', object: callee.object, args }
       }
       // `.reverse()` and `.toReversed()` — both zero-arg shapes
@@ -390,7 +442,8 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       // of state, so JS's mutate-and-return-receiver (`reverse`)
       // vs return-new-array (`toReversed`) distinction has no
       // template-level meaning; both produce a new reversed array.
-      if ((callee.property === 'reverse' || callee.property === 'toReversed') && args.length === 0) {
+      // JS takes no argument and ignores any that are passed.
+      if (callee.property === 'reverse' || callee.property === 'toReversed') {
         return { kind: 'array-method', method: callee.property, object: callee.object, args }
       }
       // `.toLowerCase()` — string-only (the IR carries a value-builtin
@@ -398,20 +451,150 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       // label is a misnomer for string methods but the mechanical
       // pipeline matches). Go uses the existing `bf_lower` helper;
       // Mojo uses Perl's native `lc`. See #1448 Tier A.
-      if (callee.property === 'toLowerCase' && args.length === 0) {
+      if (callee.property === 'toLowerCase') {
         return { kind: 'array-method', method: 'toLowerCase', object: callee.object, args }
       }
       // `.toUpperCase()` — Go uses the existing `bf_upper` helper;
       // Mojo uses Perl's native `uc`.
-      if (callee.property === 'toUpperCase' && args.length === 0) {
+      if (callee.property === 'toUpperCase') {
         return { kind: 'array-method', method: 'toUpperCase', object: callee.object, args }
       }
       // `.trim()` — Go uses the existing `bf_trim` helper; Mojo uses
       // a new `bf->trim` method that mirrors JS's "strip leading +
       // trailing whitespace" semantic via a Perl regex.
-      if (callee.property === 'trim' && args.length === 0) {
+      if (callee.property === 'trim') {
         return { kind: 'array-method', method: 'trim', object: callee.object, args }
       }
+      // `.split()` / `.split(sep)` / `.split(sep, limit)` — string →
+      // array, full JS arity. `.split()` (no separator) returns the
+      // whole string as a single element; `.split(sep)` splits on the
+      // (literal) separator; the optional `limit` caps the number of
+      // pieces. JS ignores a third+ argument. Go uses `bf_split`
+      // (`strings.Split`, optional limit, normalised to `[]any`) and
+      // `bf_arr` for the no-separator whole-string case; Mojo uses
+      // `bf->split`. The regex-separator form stays refused (the parser
+      // never reaches here for it — a regex literal arg is `unsupported`
+      // and propagates). See #1448 Tier B.
+      if (callee.property === 'split') {
+        return { kind: 'array-method', method: 'split', object: callee.object, args }
+      }
+      // Arity guard for the forms whose EXTRA argument changes the
+      // result and is not yet lowered: the `fromIndex` of `.includes` /
+      // `.indexOf` / `.lastIndexOf` (the 2-arg form), and the additional
+      // arrays of a variadic `.concat(a, b, …)`. Silently dropping those
+      // would make the SSR output *differ* from the client (worse than a
+      // build error), so they refuse with BF101 until lowered. (The
+      // single-argument forms, zero-arg defaults, and JS-ignored
+      // trailing arguments of every method are accepted by the relaxed
+      // arms above.) See #1448.
+      if (LOWERED_ARRAY_METHODS.has(callee.property)) {
+        const argName = callee.property === 'concat' ? 'other' : 'x'
+        const detail =
+          callee.property === 'concat'
+            ? 'the variadic `.concat(a, b, …)` form'
+            : `\`.${callee.property}(…)\` with ${args.length} argument(s)`
+        return {
+          kind: 'unsupported',
+          raw,
+          reason: `${detail} is not yet lowered to the Go/Mojo template adapters. Use the single-argument \`.${callee.property}(${argName})\` form, or pre-compute the value before the template.`,
+        }
+      }
+      // `.startsWith(search, position?)` / `.endsWith(search, endPosition?)`
+      // — string → boolean, full JS arity. Go uses `bf_starts_with` /
+      // `bf_ends_with` (wrapping `strings.HasPrefix` / `strings.HasSuffix`,
+      // with an optional position that re-anchors the comparison); Mojo
+      // uses `bf->starts_with` / `bf->ends_with` (substr comparison). JS
+      // ignores a third+ argument. The zero-arg form (`.startsWith()`) is
+      // refused: JS coerces the missing search to the literal string
+      // "undefined", a degenerate result not worth lowering (mirrors the
+      // `.includes()` zero-arg refusal). See #1448 Tier B.
+      if (callee.property === 'startsWith' || callee.property === 'endsWith') {
+        if (args.length === 0) {
+          return {
+            kind: 'unsupported',
+            raw,
+            reason: `\`.${callee.property}()\` with no search string is not lowered — JS coerces the missing argument to the string "undefined", a degenerate result. Pass an explicit search string, or pre-compute the value before the template.`,
+          }
+        }
+        return { kind: 'array-method', method: callee.property, object: callee.object, args }
+      }
+      // `.replace(pattern, replacement)` — string-pattern form,
+      // replacing the FIRST occurrence (JS semantics for a string
+      // pattern). Go uses `bf_replace` (`strings.Replace` with n=1);
+      // Mojo uses `bf->replace` (index/substr splice, no regex). A
+      // regex-literal pattern parses as `unsupported` (convertNode has
+      // no regex arm), so it's refused explicitly here rather than
+      // emitting a broken `.Replace` — the Perl `s///` vs Go
+      // `regexp.ReplaceAllString` flavour gap is the open design
+      // question in #1448. `replaceAll` stays refused entirely.
+      //
+      // Full JS arity: a third+ argument is ignored (the adapter reads
+      // only the pattern + replacement). The one- and zero-argument
+      // forms are refused: JS coerces the missing replacement (and
+      // pattern) to the literal string "undefined", a degenerate result
+      // (mirrors the `.includes()` / `.startsWith()` zero-arg refusal).
+      if (callee.property === 'replace') {
+        if (args.length < 2) {
+          return {
+            kind: 'unsupported',
+            raw,
+            reason: `\`.replace(${args.length === 0 ? '' : 'pattern'})\` needs both a pattern and a replacement — JS coerces the missing argument to the string "undefined", a degenerate result. Pass both arguments, or pre-compute the value before the template.`,
+          }
+        }
+        // A regex-literal pattern is the deferred form (the Perl `s///`
+        // vs Go `regexp.ReplaceAllString` flavour gap, #1448) — detect it
+        // on the TS node so the message is accurate. Any OTHER unsupported
+        // pattern/replacement (an object literal, an unsupported call, …)
+        // surfaces ITS OWN reason rather than being mislabelled as the
+        // regex form.
+        const patternNode = node.arguments[0]
+        if (patternNode && ts.isRegularExpressionLiteral(patternNode)) {
+          return {
+            kind: 'unsupported',
+            raw,
+            reason:
+              'String.prototype.replace supports only a string pattern + string replacement (the regex form is deferred); use a string pattern or wrap the expression in /* @client */',
+          }
+        }
+        const badArg =
+          args[0].kind === 'unsupported'
+            ? args[0]
+            : args[1].kind === 'unsupported'
+              ? args[1]
+              : undefined
+        if (badArg && badArg.kind === 'unsupported') {
+          return { kind: 'unsupported', raw, reason: badArg.reason }
+        }
+        return { kind: 'array-method', method: 'replace', object: callee.object, args }
+      }
+      // `.repeat(n)` — string → string (the receiver concatenated `n`
+      // times). Go uses `bf_repeat` (`strings.Repeat`, clamping a
+      // negative count to "" instead of panicking); Mojo uses
+      // `bf->repeat` (Perl's `x` operator). JS throws RangeError for a
+      // negative count, but SSR templates degrade to the empty string
+      // rather than crashing the render. See #1448 Tier B.
+      // Full JS arity: `.repeat()` (no count) is `repeat(0)` → "" (JS
+      // coerces the missing count to 0, not a RangeError), and a
+      // second+ argument is ignored. The adapter supplies the `0` for
+      // the no-argument form. See #1448 Tier B.
+      if (callee.property === 'repeat') {
+        return { kind: 'array-method', method: 'repeat', object: callee.object, args }
+      }
+      // `.padStart(target, pad?)` / `.padEnd(target, pad?)` — string →
+      // string, padded to `target` length with `pad` (default a single
+      // space) repeated + truncated to fill. Go uses `bf_pad_start` /
+      // `bf_pad_end`; Mojo uses `bf->pad_start` / `bf->pad_end`. Both
+      // count length in code points (Go runes / Perl chars) so they
+      // stay byte-equal — this differs from JS's UTF-16-unit length
+      // only for astral-plane receivers, which are vanishingly rare in
+      // numeric / space padding. See #1448 Tier B.
+      // Full JS arity: `.padStart()` (no target) is `padStart(0)` → the
+      // receiver unchanged (JS coerces the missing target to 0), and a
+      // third+ argument is ignored. The adapter supplies the `0` for the
+      // no-argument form and reads only target + padString.
+      if (callee.property === 'padStart' || callee.property === 'padEnd') {
+        return { kind: 'array-method', method: callee.property, object: callee.object, args }
+      }
       // `.sort(cmp)` / `.toSorted(cmp)` (#1448 Tier B). The comparator
       // is extracted into a structured `SortComparator` at parse time;
       // unrecognised shapes fall through to `unsupported` so adapters

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

@@ -3,55 +3,170 @@
  */
 
 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 container. 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
- * static sibling rendered as a sibling of the loop's items too, so
- * `children[idx]` access is shifted exactly as it is under an element parent
- * (#1688). Before this, a static sibling before a `.map()` inside a
- * (self-portaling) component dropped the first item's nested child component
- * during hydration because the offset was silently zero.
+ * 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>()
-  const recordChildren = (children: IRNode[]): void => {
-    let nonLoopCount = 0
+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') {
-        if (nonLoopCount > 0) offsets.set(child, nonLoopCount)
-      } else if (producesDomChild(child)) {
-        nonLoopCount++
+        // 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)
       }
     }
   }
   const containerVisit = ({ node, descend }: { node: { children: IRNode[] }; descend: () => void }): void => {
-    recordChildren(node.children)
+    recordRun(node.children, [])
     descend()
   }
   walkIR(root, null, {
@@ -68,6 +183,29 @@ export function computeLoopSiblingOffsets(root: IRNode): Map<IRLoop, number> {
   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.
  *
@@ -129,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,
@@ -258,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.
@@ -286,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
@@ -440,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, {
@@ -595,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,
@@ -854,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
@@ -953,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
@@ -983,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),
@@ -1003,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, {
@@ -1051,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 {
@@ -1069,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[] {
@@ -1144,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
 }