@barefootjs/jsx 0.18.5 → 0.19.0

package/src/index.ts

@@ -49,6 +49,7 @@ export type {
   ParamInfo,
   PropertyInfo,
   MemoInfo,
+  ConstantInfo,
   TypeInfo,
   TypeDefinition,
   SourceLocation,
@@ -87,6 +88,9 @@ export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
 export { rewriteImportsForTemplate } from './adapters/template-imports.ts'
 export { emitParsedExpr, groupBinaryOperand, isStringTypedOperand, isStringConcatBinary } from './adapters/parsed-expr-emitter.ts'
 export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
+export { collectLoopBoundNames } from './adapters/loop-bound-names.ts'
+export { evaluateSignalInit, tryEvaluateSignalInit, type SignalInitEvalResult } from './signal-init-eval.ts'
+export { evaluateStaticLiteral, isFullyStaticLiteral, resolveStaticLoopSource } from './static-literal.ts'
 export { importsSearchParams, searchParamsLocalNames, envSignalLocalNames, envSignalReaderFor, ENV_SIGNAL_READERS, queryHrefLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
 export type { EnvSignalReader } from './adapters/env-signal.ts'
 export { matchQueryHrefCall, queryHrefArgs, type QueryHrefCall, type QueryHrefTriple } from './query-href-lowering.ts'
@@ -116,6 +120,13 @@ export { emitIRNode } from './adapters/ir-node-emitter.ts'
 export type { IRNodeEmitter, EmitIRNode } from './adapters/ir-node-emitter.ts'
 export { emitAttrValue } from './adapters/attr-value-emitter.ts'
 export type { AttrValueEmitter } from './adapters/attr-value-emitter.ts'
+export {
+  isDangerousInnerHtmlAttr,
+  resolveDangerousInnerHtml,
+  dangerousInnerHtmlMetacharViolation,
+  dangerousInnerHtmlDiagnostic,
+} from './adapters/dangerous-inner-html.ts'
+export type { DangerousInnerHtmlResolution } from './adapters/dangerous-inner-html.ts'
 
 // Client JS Generator
 export { generateClientJs, generateClientJsWithSourceMap, analyzeClientNeeds } from './ir-to-client-js/index.ts'
@@ -272,15 +283,20 @@ export interface BuildOptions {
    *   - `'treeshake'` (default) — bundle only the runtime exports this
    *     project's compiled client JS actually imports, plus a small
    *     always-kept public mount API (`render`, `hydrate`, etc.).
+   *   - `'treeshake-exact'` — same collection, but without the always-kept
+   *     set. Smaller output; a hand-written page script the CLI never
+   *     compiles must list any runtime names it calls directly in
+   *     `runtimeKeep`, or they're silently dropped.
    *   - `'full'` — copy the entire prebuilt runtime bundle verbatim.
    * See `@barefootjs/cli`'s `runtime-treeshake.ts` for the collector and
    * `ALWAYS_KEEP_RUNTIME_EXPORTS` for the always-kept names.
    */
-  runtimeBundle?: 'treeshake' | 'full'
+  runtimeBundle?: 'treeshake' | 'treeshake-exact' | 'full'
   /**
    * Extra `@barefootjs/client*` export names to force-keep in `barefoot.js`
-   * under `runtimeBundle: 'treeshake'` — for names only ever referenced
-   * from hand-written page scripts the CLI never compiles.
+   * under `runtimeBundle: 'treeshake'` or `'treeshake-exact'` — for names
+   * only ever referenced from hand-written page scripts the CLI never
+   * compiles.
    */
   runtimeKeep?: string[]
 }
@@ -306,6 +322,7 @@ export { ErrorCodes, createError, formatError, generateCodeFrame } from './error
 // Expression Parser
 export { parseExpression, tsNodeToParsedExpr, asCallbackMethodCall, CALLBACK_METHODS, sortComparatorFromArrow, serializeParsedExpr, freeVarsInBody, freeIdentifiers, materializeGetterCalls, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, parseBlockBodyTolerant, foldBlockToExpr, predicateTernaryToLogical, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember, type FoldBlockOptions } from './expression-parser.ts'
 export type { StyleObjectEntry } from './expression-parser.ts'
+export { PARSED_EXPR_KINDS } from './expression-parser.ts'
 export type { ParsedExpr, ObjectLiteralProperty, ParsedStatement, SortComparator, SortKey, FlatDepth, SupportLevel, SupportResult, TemplatePart } from './expression-parser.ts'
 export { buildLoopChainExpr } from './loop-chain.ts'
 export type { LoopChainInputs } from './loop-chain.ts'

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

@@ -6,7 +6,8 @@ import { type IRNode, type IRElement, type IRComponent, type IRLoop, type IRProp
 import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, LoopOffset, NestedLoop } from './types.ts'
 import { attrValueToString, freeIdsFromRefs, quotePropName, PROPS_PARAM } from './utils.ts'
 import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings } from './reactivity.ts'
-import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate } from './html-template.ts'
+import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, type SkeletonSlotPaths } from './html-template.ts'
+import { templateRootIsSvg } from './control-flow/stringify/template-parse.ts'
 import { expandDynamicPropValue, expandConstantForReactivity } from './prop-handling.ts'
 import { walkIR, stopAt } from './walker.ts'
 import { buildLoopChainExpr } from '../loop-chain.ts'
@@ -385,6 +386,7 @@ export function collectInnerLoops(
           arrayFreeIdentifiers: n.arrayFreeIdentifiers,
           param: n.param,
           paramBindings: n.paramBindings,
+          index: n.index,
           key: n.key,
           markerId: n.markerId,
           bodyIsMultiRoot: n.bodyIsMultiRoot,
@@ -673,6 +675,7 @@ export function collectElements(
       let template = ''
       let staticItemTemplate: string | undefined
       let skeletonTemplate: string | undefined
+      let skeletonPaths: SkeletonSlotPaths | undefined
       if (l.childComponent) {
         template = '' // childComponent path uses createComponent directly
         // CSR materialize fallback (#1268): when the loop array references an
@@ -724,10 +727,18 @@ export function collectElements(
           // expressions, …) and returns `null` for anything it can't prove
           // safe; the plan builder (`build-loop.ts`) falls back to the
           // per-row `template` above whenever this stays `undefined`.
-          skeletonTemplate = buildLoopSkeletonTemplate(l.children[0], {
+          const skeletonSafeSlots = {
             reactiveAttrKeys: new Set(bindings.reactiveAttrs.map(a => `${a.childSlotId}::${a.attrName}`)),
             reactiveTextSlotIds: new Set(bindings.reactiveTexts.map(t => t.slotId)),
-          }) ?? undefined
+          }
+          skeletonTemplate = buildLoopSkeletonTemplate(l.children[0], skeletonSafeSlots) ?? undefined
+          // Direct child-index paths (perf, #2143): only attempted when the
+          // skeleton itself hoisted, and skipped for SVG roots for now (the
+          // `<svg>`-wrap namespace fix-up is orthogonal and untested against
+          // this path model — safe fallback to qsa/$t for those loops).
+          if (skeletonTemplate && !templateRootIsSvg(skeletonTemplate)) {
+            skeletonPaths = computeSkeletonSlotPaths(l.children[0], skeletonSafeSlots) ?? undefined
+          }
         }
       }
 
@@ -748,6 +759,7 @@ export function collectElements(
         template,
         staticItemTemplate,
         skeletonTemplate,
+        skeletonPaths,
         childEventHandlers: childHandlers,
         bindings,
         childComponent: l.childComponent,

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

@@ -58,6 +58,7 @@ import type { DepthLevel } from '../shared.ts'
 import {
   destructureLoopParam,
   loopKeyFn,
+  nestedLoopIndexAlias,
 } from '../shared.ts'
 import type {
   InnerLoopPlan,
@@ -114,8 +115,8 @@ export function buildInnerLoopsPlan(args: BuildInnerLoopsArgs): InnerLoopsPlan {
     const useReactive = refsParent && !!inner.template
 
     const emit: InnerLoopReactiveEmit | InnerLoopStaticEmit = useReactive
-      ? buildReactiveEmit(inner, level, wrapOuter)
-      : buildStaticEmit(inner, level)
+      ? buildReactiveEmit(inner, level, wrapOuter, uidSuffix)
+      : buildStaticEmit(inner, level, uidSuffix)
 
     const arrayExpr = useReactive ? wrapOuter(inner.array) : inner.array
 
@@ -153,6 +154,7 @@ function buildReactiveEmit(
   inner: NestedLoop,
   level: DepthLevel,
   wrapOuter: (expr: string) => string,
+  uidSuffix: string,
 ): InnerLoopReactiveEmit {
   const wrapInner = (expr: string) => wrapLoopParamAsAccessor(expr, inner.param, inner.paramBindings)
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(inner.param, inner.paramBindings)
@@ -218,7 +220,14 @@ function buildReactiveEmit(
   // The destructure unwrap (when `inner.param` is a binding pattern)
   // has to land before the preamble so the preamble's bare-binding
   // references resolve.
+  //
+  // The index alias (#2218) lands first — before both the unwrap and the
+  // preamble — since either may reference the user's index name (e.g. a
+  // `const rowTag = \`row-${i}\`` preamble line), and both run before the
+  // cloned-template IIFE that may also reference it.
   const preludeStatements: string[] = []
+  const indexAlias = nestedLoopIndexAlias(inner, `__innerIdx${uidSuffix}`, paramHead, level.comps, level.events)
+  if (indexAlias) preludeStatements.push(indexAlias)
   if (paramUnwrap) preludeStatements.push(paramUnwrap)
   if (inner.mapPreamble) preludeStatements.push(wrapInner(wrapOuter(inner.mapPreamble)))
 
@@ -240,7 +249,7 @@ function buildReactiveEmit(
   }
 }
 
-function buildStaticEmit(inner: NestedLoop, level: DepthLevel): InnerLoopStaticEmit {
+function buildStaticEmit(inner: NestedLoop, level: DepthLevel, uidSuffix: string): InnerLoopStaticEmit {
   // Static `forEach` iterates with the literal item as its first param, so
   // no signal-accessor rewrite is needed — emit the preamble verbatim
   // before the component/event setup so prop getters and event handlers
@@ -248,7 +257,15 @@ function buildStaticEmit(inner: NestedLoop, level: DepthLevel): InnerLoopStaticE
   // wrapping the callback would rewrite `s.x` to `s().x` and throw at
   // runtime when the callback closes over the static inner param (#1244,
   // PR #1352 Copilot review).
-  const preludeStatements: string[] = inner.mapPreamble ? [inner.mapPreamble] : []
+  //
+  // The index alias (#2218) lands first, same rationale as the reactive
+  // path: `forEach`'s second param is the synthetic `__innerIdx<uid>`, not
+  // the user's index name, so a preamble/prop/event that reads it needs the
+  // alias bound before anything else runs.
+  const preludeStatements: string[] = []
+  const indexAlias = nestedLoopIndexAlias(inner, `__innerIdx${uidSuffix}`, inner.param, level.comps, level.events)
+  if (indexAlias) preludeStatements.push(indexAlias)
+  if (inner.mapPreamble) preludeStatements.push(inner.mapPreamble)
   return {
     mode: 'static',
     rawKey: inner.key ?? null,

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

@@ -57,7 +57,7 @@ function wrapAttrValueExpression(value: AttrValue, wrap: (s: string) => string):
       return AttrValueOf.spread(wrap(value.expr), value.templateExpr ? wrap(value.templateExpr) : undefined)
   }
 }
-import { destructureLoopParam, loopKeyFn, buildCompSelector } from '../shared.ts'
+import { destructureLoopParam, loopKeyFn, buildCompSelector, nestedLoopIndexAlias } from '../shared.ts'
 import { BF_HOST, BF_AT } from '@barefootjs/shared'
 import type {
   BranchChildComponentInit,
@@ -269,6 +269,17 @@ export function buildBranchInnerLoopsPlan(
       handler: wrapInner(ev.handler),
     }))
 
+    // Index-param gating runs against the RAW (pre-wrap) component/event
+    // data — wrapping only rewrites loop-param references, never the
+    // index name, so it doesn't affect whether the index is referenced.
+    const indexAlias = nestedLoopIndexAlias(
+      inner,
+      `__bidxbr_${i}`,
+      paramHead,
+      inner.childComponents ?? [],
+      inner.bindings.events,
+    )
+
     const reactiveTexts: BranchInnerLoopText[] = inner.bindings.reactiveTexts.map(text => ({
       slotId: text.slotId,
       wrappedExpression: wrapBoth(text.expression),
@@ -286,6 +297,7 @@ export function buildBranchInnerLoopsPlan(
       keyFn: loopKeyFn(inner),
       paramHead,
       paramUnwrap,
+      indexAlias,
       wrappedTemplate: inner.template!,
       wrappedKey,
       keyDepth: 1,

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

@@ -103,6 +103,7 @@ export function buildPlainLoopPlan(elem: TopLevelLoop, profileComponentName?: st
     mapPreambleWrapped: elem.mapPreamble ? wrap(elem.mapPreamble) : '',
     template: elem.template,
     skeletonTemplate: elem.skeletonTemplate,
+    skeletonPaths: elem.skeletonPaths,
     reactiveEffects: hasReactive ? buildLoopReactiveEffectsPlan(elem, profileComponentName) : null,
     childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,

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

@@ -108,6 +108,15 @@ export interface BranchInnerLoop {
   paramHead: string
   /** Body-entry unwrap statement (empty when no destructured param). */
   paramUnwrap: string
+  /**
+   * Body-entry index-alias statement (#2218), or `null` when the inner
+   * loop declares no index param or never references it. Binds the user's
+   * index name to the synthetic `__bidx<uid>` renderItem param — mirrors
+   * `InnerLoopReactiveEmit`'s prelude alias in `plan/inner-loop.ts`. Must
+   * be emitted before `paramUnwrap` and the template clone, since either
+   * may reference the index.
+   */
+  indexAlias: string | null
   /** Already-wrapped HTML template for one inner-loop item. */
   wrappedTemplate: string
   /** Pre-wrapped key expression for setAttribute, or null when no key. */

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

@@ -23,6 +23,7 @@ import type {
   TopLevelLoop,
 } from '../../types.ts'
 import type { IRLoopChildComponent } from '../../../types.ts'
+import type { SkeletonSlotPaths } from '../../html-template.ts'
 import type { ReactiveEffectsPlan } from './reactive-effects.ts'
 import type { InnerLoopsPlan } from './inner-loop.ts'
 
@@ -103,6 +104,14 @@ interface PlainLoopVariant extends DynamicLoopCommon {
    * stringifier falls back to the legacy per-row `emitTemplateCloneInline`.
    */
   skeletonTemplate?: string
+  /**
+   * Compile-time child-index paths for `skeletonTemplate`'s dynamic slots
+   * (perf, #2143). When present, the stringifier resolves attr/text/ref
+   * slots via direct `.firstChild`/`.nextSibling` property chains on a
+   * fresh clone instead of `qsa`/`$t`, falling back to the runtime lookup
+   * only for hydration (`__existing`) or any slot missing from the map.
+   */
+  skeletonPaths?: SkeletonSlotPaths
   /** Resolved reactive-effects plan — null forces the single-line renderItem shape. */
   reactiveEffects: ReactiveEffectsPlan | null
   /**

package/src/ir-to-client-js/control-flow/shared.ts

@@ -20,21 +20,118 @@ import { emitListenerBlock } from './stringify/event-listener.ts'
 import { nameForRegistryRef } from '../component-scope.ts'
 import { BF_SCOPE, BF_HOST, BF_AT } from '@barefootjs/shared'
 import type { LoopChildRefBinding } from './plan/loop.ts'
+import {
+  extractFreeIdentifiersFromText,
+  extractFreeIdentifiersFromStatementText,
+  extractFreeIdentifiersFromTemplateText,
+} from '../csr-substitute.ts'
 
 /**
  * Build the `keyFn` argument for mapArray / reconcileElements. `null` when
- * the loop has no key expression. Narrowing on `loop.kind` keeps `index`
- * off `NestedLoop` (nested loops never thread an explicit index parameter)
- * and lets the compiler verify we handled every flavour exhaustively.
+ * the loop has no key expression. Every `CollectedLoop` variant (top-level /
+ * branch / nested) carries an `index: string | null` field (#2218 threaded
+ * it onto `NestedLoop` too), so the index param — when present — is always
+ * appended to the keyFn's own parameter list. mapArray invokes `keyFn(item,
+ * i)` directly with the numeric index, independent of the synthetic
+ * `__innerIdx<uid>` binding used inside a nested loop's renderItem body
+ * (see `nestedLoopReferencesIndex` below), so no aliasing is needed here.
  */
 export function loopKeyFn(loop: CollectedLoop): string {
   if (loop.key === null) return 'null'
-  const params = loop.kind === 'nested'
-    ? loop.param
-    : `${loop.param}${loop.index ? `, ${loop.index}` : ''}`
+  const params = `${loop.param}${loop.index ? `, ${loop.index}` : ''}`
   return `(${params}) => String(${loop.key})`
 }
 
+/**
+ * Does a nested inner loop's body reference its own declared index
+ * parameter (e.g. `i` from `.map((item, i) => ...)`)? Scans every surface
+ * the renderItem/forEach body can read the index from — the key
+ * expression, reactive text/attr expressions, the map-preamble statements,
+ * the per-item HTML template's `${...}` interpolations, per-item events,
+ * ref callbacks, and child-component props — so the byte-stable gate only
+ * fires when the index is truly used (mirrors #2189's handler-only gate
+ * for delegated events, `indexBindingLine` in `stringify/event-delegation.ts`).
+ *
+ * `comps` / `events` are passed separately (rather than read off `inner`)
+ * because callers hold them in different shapes at different points in the
+ * build pipeline — `DepthLevel.comps`/`.events` for the plain inner-loop
+ * path, `inner.childComponents`/`inner.bindings.events` for the loop-child-
+ * arm (conditional-branch) path.
+ *
+ * AST-based throughout (never regex) per repo convention — a token-level
+ * scan would false-match a property access like `item.i` as a reference to
+ * an index param named `i`.
+ */
+export function nestedLoopReferencesIndex(
+  inner: NestedLoop,
+  comps: readonly IRLoopChildComponent[],
+  events: readonly LoopChildEvent[],
+): boolean {
+  const index = inner.index
+  if (!index) return false
+
+  const exprRefs = (text: string | null | undefined, precomputed?: ReadonlySet<string>): boolean => {
+    if (precomputed) return precomputed.has(index)
+    if (!text) return false
+    return extractFreeIdentifiersFromText(text).has(index)
+  }
+
+  if (exprRefs(inner.key)) return true
+  for (const t of inner.bindings.reactiveTexts) {
+    if (exprRefs(t.expression, t.freeIdentifiers)) return true
+  }
+  for (const a of inner.bindings.reactiveAttrs) {
+    if (exprRefs(a.expression, a.freeIdentifiers)) return true
+  }
+  if (inner.mapPreamble && extractFreeIdentifiersFromStatementText(inner.mapPreamble).has(index)) return true
+  if (inner.template && extractFreeIdentifiersFromTemplateText(inner.template).has(index)) return true
+  for (const ev of events) {
+    if (exprRefs(ev.handler)) return true
+  }
+  for (const r of inner.bindings.refs) {
+    if (exprRefs(r.callback)) return true
+  }
+  for (const c of comps) {
+    for (const p of c.props) {
+      if (exprRefs(attrValueToString(p.value))) return true
+    }
+    if (c.children?.length) {
+      const childrenExpr = irChildrenToJsExpr(c.children)
+      if (childrenExpr && exprRefs(childrenExpr)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Build the prelude alias statement that binds a nested inner loop's index
+ * param to the synthetic numeric-index value mapArray/forEach passes into
+ * renderItem (#2218), or `null` when no alias is needed. Gated by
+ * `nestedLoopReferencesIndex` for byte-for-byte stability — loops that
+ * declare an index but never read it emit no extra line. `paramHead` guards
+ * against the (JS-illegal, can't actually happen) case where the index name
+ * collides with the loop's own emitted item-parameter identifier — mirrors
+ * the self-alias guard in #2189's `indexBindingLine`.
+ *
+ * `syntheticIndexVar` is the already-formatted variable name the caller's
+ * stringifier binds the numeric index to (`__innerIdx<uid>` in
+ * `stringify/inner-loop.ts`, `__bidx<uid>` in `stringify/loop-child-arm.ts`)
+ * — passed in rather than assembled here so this helper doesn't need to
+ * know which emission family is calling it.
+ */
+export function nestedLoopIndexAlias(
+  inner: NestedLoop,
+  syntheticIndexVar: string,
+  paramHead: string,
+  comps: readonly IRLoopChildComponent[],
+  events: readonly LoopChildEvent[],
+): string | null {
+  const index = inner.index
+  if (!index || index === paramHead) return null
+  if (!nestedLoopReferencesIndex(inner, comps, events)) return null
+  return `const ${index} = ${syntheticIndexVar}`
+}
+
 /**
  * Wrap each ref's `callback` expression with the loop-param accessor and
  * return `LoopChildRefBinding[]` ready for the stringifier. For dynamic

package/src/ir-to-client-js/control-flow/stringify/inner-loop.ts

@@ -33,7 +33,7 @@
 import { keyAttrName, profileBindingId } from '../../utils.ts'
 import { emitComponentAndEventSetup } from '../shared.ts'
 import { emitAttrUpdate } from '../../emit-reactive.ts'
-import { emitMultiRootTemplateCloneLines } from './template-parse.ts'
+import { emitMultiRootTemplateCloneLines, templateRootIsSvg } from './template-parse.ts'
 import { emitLoopChildRefs } from './loop.ts'
 import type {
   InnerLoopPlan,
@@ -82,7 +82,16 @@ function emitReactive(lines: string[], inner: InnerLoopPlan, indent: string, pc:
     lines.push(`${innerIndent}  __innerEl${uid}.__bfExtras = __innerExtras${uid}`)
     lines.push(`${indent}  }`)
   } else {
-    lines.push(`${indent}  let __innerEl${uid} = __existing ?? (() => { const __t = document.createElement('template'); __t.innerHTML = \`${emit.wrappedTemplate}\`; return __t.content.firstElementChild.cloneNode(true) })()`)
+    // SVG-rooted item templates must parse inside a synthetic `<svg>` wrap
+    // (#2219): `template.innerHTML` parses in the HTML namespace, so a bare
+    // `<line>`/`<circle>` root clones as an HTMLUnknownElement and the SVG
+    // renderer silently draws nothing. Mirrors `templateRootIsSvg` handling
+    // on the top-level (#135/#1088) and branch-arm paths; HTML-rooted
+    // templates keep byte-identical output.
+    const isSvg = templateRootIsSvg(emit.wrappedTemplate)
+    const innerHtml = isSvg ? `<svg>${emit.wrappedTemplate}</svg>` : emit.wrappedTemplate
+    const childPath = isSvg ? '.firstElementChild.firstElementChild' : '.firstElementChild'
+    lines.push(`${indent}  let __innerEl${uid} = __existing ?? (() => { const __t = document.createElement('template'); __t.innerHTML = \`${innerHtml}\`; return __t.content${childPath}.cloneNode(true) })()`)
   }
   if (emit.wrappedKey) {
     lines.push(`${indent}  __innerEl${uid}.setAttribute('${keyAttrName(inner.keyDepth)}', String(${emit.wrappedKey}))`)

package/src/ir-to-client-js/control-flow/stringify/loop-child-arm.ts

@@ -86,6 +86,11 @@ export function stringifyBranchInnerLoops(
     const uid = inner.uidSuffix
     lines.push(`${indent}{ const __bic${uid} = ${inner.containerExpr}`)
     lines.push(`${indent}if (__bic${uid}) mapArray(() => ${inner.arrayExpr} || [], __bic${uid}, ${inner.keyFn}, (${inner.paramHead}, __bidx${uid}, __existing) => {`)
+    // Index alias (#2218) lands first — before the destructure unwrap and
+    // the template clone, either of which may reference the index.
+    if (inner.indexAlias) {
+      lines.push(`${indent}  ${inner.indexAlias}`)
+    }
     if (inner.paramUnwrap) {
       lines.push(`${indent}  ${inner.paramUnwrap}`)
     }

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

@@ -27,7 +27,8 @@
 import { emitRefCall, varSlotId, profileBindingId } from '../../utils.ts'
 import { emitAttrUpdate } from '../../emit-reactive.ts'
 import { stringifyReactiveEffects } from './reactive-effects.ts'
-import { emitTemplateCloneInline, emitLoopItemElementSetup, emitHoistedTemplateDecl, hoistedCloneExpr } from './template-parse.ts'
+import { emitTemplateCloneInline, emitLoopItemElementSetup, emitHoistedTemplateDecl, hoistedCloneExpr, templateRootIsSvg, multiRootTemplateNeedsSvgWrap } from './template-parse.ts'
+import { buildSkeletonPathPlan, type SkeletonPathPlan } from './skeleton-paths.ts'
 import { stringifyComponentLoop } from './component-loop.ts'
 import { stringifyCompositeLoop } from './composite-loop.ts'
 import type { LoopChildRefBinding, LoopPlan, PlainLoopPlan, StaticLoopPlan } from '../plan/types.ts'
@@ -47,14 +48,18 @@ import type { LoopChildRefBinding, LoopPlan, PlainLoopPlan, StaticLoopPlan } fro
 export function emitLoopChildRefs(
   lines: string[],
   refs: readonly LoopChildRefBinding[],
-  opts: { indent: string; elVar: string; bodyIsMultiRoot: boolean },
+  opts: { indent: string; elVar: string; bodyIsMultiRoot: boolean; elementIndexBySlot?: ReadonlyMap<string, number> },
 ): void {
   if (refs.length === 0) return
-  const { indent, elVar, bodyIsMultiRoot } = opts
+  const { indent, elVar, bodyIsMultiRoot, elementIndexBySlot } = opts
   const lookup = bodyIsMultiRoot ? 'qsaItem' : 'qsa'
   for (const ref of refs) {
     const varName = `__rf_${varSlotId(ref.childSlotId)}`
-    lines.push(`${indent}{ const ${varName} = ${lookup}(${elVar}, '[bf="${ref.childSlotId}"]')`)
+    const pIdx = elementIndexBySlot?.get(ref.childSlotId)
+    const lookupExpr = pIdx !== undefined
+      ? `__p ? __p[${pIdx}] : ${lookup}(${elVar}, '[bf="${ref.childSlotId}"]')`
+      : `${lookup}(${elVar}, '[bf="${ref.childSlotId}"]')`
+    lines.push(`${indent}{ const ${varName} = ${lookupExpr}`)
     lines.push(`${indent}if (${varName}) ${emitRefCall(ref.callback, varName)} }`)
   }
 }
@@ -181,10 +186,37 @@ export function stringifyPlainLoop(
       singleRootLayout: 'inline',
     })
   }
+  // Direct child-index paths (perf, #2143): only reachable when hoistedTpl
+  // is set, which itself requires a single-root, conditional-free body — so
+  // `reactiveEffects.conditionals` is always empty here and needs no path
+  // handling. `__p` is `null` on the hydration branch (`__existing` truthy)
+  // since the skeleton's empty markers/omitted attrs don't describe the
+  // SSR-rendered tree; every resolution falls back to qsa/$t there.
+  let pathPlan: SkeletonPathPlan | null = null
+  if (hoistedTpl && plan.skeletonPaths) {
+    const elementSlotIds = [
+      ...(reactiveEffects?.attrSlots.map(s => s.slotId) ?? []),
+      ...childRefs.map(r => r.childSlotId),
+    ]
+    const textSlotIds = reactiveEffects?.outerTexts.map(t => t.slotId) ?? []
+    if (elementSlotIds.length > 0 || textSlotIds.length > 0) {
+      const built = buildSkeletonPathPlan(plan.skeletonPaths, '__el', { elementSlotIds, textSlotIds })
+      if (built.arrayElems.length > 0) {
+        pathPlan = built
+        lines.push(`${bodyIndent}const __p = __existing ? null : [${built.arrayElems.join(', ')}]`)
+      }
+    }
+  }
   if (reactiveEffects !== null) {
-    stringifyReactiveEffects(lines, reactiveEffects, { indent: bodyIndent, elVar: '__el', bodyIsMultiRoot })
+    stringifyReactiveEffects(lines, reactiveEffects, {
+      indent: bodyIndent,
+      elVar: '__el',
+      bodyIsMultiRoot,
+      elementIndexBySlot: pathPlan?.elementIndexBySlot,
+      textIndexBySlot: pathPlan?.textIndexBySlot,
+    })
   }
-  emitLoopChildRefs(lines, childRefs, { indent: bodyIndent, elVar: '__el', bodyIsMultiRoot })
+  emitLoopChildRefs(lines, childRefs, { indent: bodyIndent, elVar: '__el', bodyIsMultiRoot, elementIndexBySlot: pathPlan?.elementIndexBySlot })
   lines.push(`${bodyIndent}return __el`)
   lines.push(`${topIndent}}, '${markerId}'${loopBfId})`)
 }
@@ -283,15 +315,26 @@ export function stringifyStaticLoop(lines: string[], plan: StaticLoopPlan): void
   lines.push(`      let __iterEl = ${containerVar}.children[${childIndexExpr}]`)
   if (csrMaterialize) {
     lines.push(`      if (!__iterEl) {`)
+    // SVG-rooted item templates parse inside a synthetic `<svg>` wrap and
+    // descend one extra level (#2219) — `template.innerHTML` alone parses in
+    // the HTML namespace and the materialized elements would never draw.
+    // Mirrors `templateRootIsSvg` handling on the reactive clone paths;
+    // HTML-rooted templates keep byte-identical output. Multi-root fragments
+    // use the fragment-aware predicate so an `<svg>`-container-first fragment
+    // isn't over-wrapped (#2233 Copilot review).
+    const isSvg = csrMaterialize.bodyIsMultiRoot
+      ? multiRootTemplateNeedsSvgWrap(csrMaterialize.itemTemplate)
+      : templateRootIsSvg(csrMaterialize.itemTemplate)
+    const itemHtml = isSvg ? `<svg>${csrMaterialize.itemTemplate}</svg>` : csrMaterialize.itemTemplate
     if (csrMaterialize.bodyIsMultiRoot) {
       // Multi-root: clone every top-level sibling of the per-item template and
       // insert them in order. `__iterEl` is the first root (the one reactive
       // bindings attach to); the rest land alongside it via insertBefore.
       lines.push(`        const __mtpl = document.createElement('template')`)
-      lines.push(`        __mtpl.innerHTML = \`${csrMaterialize.itemTemplate}\``)
+      lines.push(`        __mtpl.innerHTML = \`${itemHtml}\``)
       lines.push(`        const __anchor = ${containerVar}.children[${childIndexExpr}] ?? null`)
       lines.push(`        let __first = null`)
-      lines.push(`        let __sib = __mtpl.content.firstElementChild`)
+      lines.push(`        let __sib = __mtpl.content${isSvg ? '.firstElementChild' : ''}.firstElementChild`)
       lines.push(`        while (__sib) {`)
       lines.push(`          const __next = __sib.nextElementSibling`)
       lines.push(`          const __cloned = __sib.cloneNode(true)`)
@@ -302,8 +345,8 @@ export function stringifyStaticLoop(lines: string[], plan: StaticLoopPlan): void
       lines.push(`        __iterEl = __first`)
     } else {
       lines.push(`        const __tpl = document.createElement('template')`)
-      lines.push(`        __tpl.innerHTML = \`${csrMaterialize.itemTemplate}\``)
-      lines.push(`        const __cloned = __tpl.content.firstElementChild`)
+      lines.push(`        __tpl.innerHTML = \`${itemHtml}\``)
+      lines.push(`        const __cloned = __tpl.content${isSvg ? '.firstElementChild' : ''}.firstElementChild`)
       lines.push(`        if (__cloned) {`)
       lines.push(`          const __anchor = ${containerVar}.children[${childIndexExpr}] ?? null`)
       lines.push(`          ${containerVar}.insertBefore(__cloned, __anchor)`)

package/src/ir-to-client-js/control-flow/stringify/reactive-effects.ts

@@ -40,6 +40,16 @@ export interface StringifyReactiveEffectsOptions {
    * `<!--bf-loop-i-->`-bounded siblings). Optional — defaults to `false`.
    */
   bodyIsMultiRoot?: boolean
+  /**
+   * Compile-time `__p` index for each attr slotId (perf, #2143) — see
+   * `buildSkeletonPathPlan`. When a slot has an entry, the emitted lookup
+   * becomes `__p ? __p[i] : qsa(...)` instead of the bare `qsa(...)` call;
+   * `__p` is `null` on the hydration branch (`__existing`), so hydration
+   * still resolves through the battle-tested runtime lookup.
+   */
+  elementIndexBySlot?: ReadonlyMap<string, number>
+  /** Same as `elementIndexBySlot`, for text-marker slots (`$t`). */
+  textIndexBySlot?: ReadonlyMap<string, number>
 }
 
 export function stringifyReactiveEffects(
@@ -47,7 +57,7 @@ export function stringifyReactiveEffects(
   plan: ReactiveEffectsPlan,
   opts: StringifyReactiveEffectsOptions,
 ): void {
-  const { indent, elVar, bodyIsMultiRoot } = opts
+  const { indent, elVar, bodyIsMultiRoot, elementIndexBySlot, textIndexBySlot } = opts
   const lookup = bodyIsMultiRoot ? 'qsaItem' : 'qsa'
   const pc = plan.profileComponentName
   const bindingBfId = (slotId: string): string => profileBindingId(pc, slotId)
@@ -55,7 +65,11 @@ export function stringifyReactiveEffects(
   // 1. Reactive attribute effects (one qsa per slot, then per-attr createEffect).
   for (const slot of plan.attrSlots) {
     const varName = `__ra_${varSlotId(slot.slotId)}`
-    lines.push(`${indent}{ const ${varName} = ${lookup}(${elVar}, '[bf="${slot.slotId}"]')`)
+    const pIdx = elementIndexBySlot?.get(slot.slotId)
+    const lookupExpr = pIdx !== undefined
+      ? `__p ? __p[${pIdx}] : ${lookup}(${elVar}, '[bf="${slot.slotId}"]')`
+      : `${lookup}(${elVar}, '[bf="${slot.slotId}"]')`
+    lines.push(`${indent}{ const ${varName} = ${lookupExpr}`)
     lines.push(`${indent}if (${varName}) {`)
     for (const attr of slot.attrs) {
       lines.push(`${indent}  createEffect(() => {`)
@@ -69,7 +83,7 @@ export function stringifyReactiveEffects(
 
   // 2. Outer text effects (slots NOT inside any conditional branch).
   for (const text of plan.outerTexts) {
-    emitOuterText(lines, indent, elVar, text, bindingBfId(text.slotId))
+    emitOuterText(lines, indent, elVar, text, bindingBfId(text.slotId), textIndexBySlot?.get(text.slotId))
   }
 
   // 3. Reactive conditionals — each emits an insert(...) over `elVar` whose
@@ -85,9 +99,16 @@ function emitOuterText(
   elVar: string,
   text: ReactiveTextEffect,
   bfId: string = '',
+  pIdx?: number,
 ): void {
   const varName = `__rt_${varSlotId(text.slotId)}`
-  lines.push(`${indent}{ const [${varName}] = $t(${elVar}, '${text.slotId}')`)
+  if (pIdx !== undefined) {
+    // Direct-path resolution (#2143): `__p` holds the marker Comment node;
+    // `tAfter` mirrors `$t`'s create-if-absent Text-node semantics exactly.
+    lines.push(`${indent}{ const ${varName} = __p ? tAfter(__p[${pIdx}]) : $t(${elVar}, '${text.slotId}')[0]`)
+  } else {
+    lines.push(`${indent}{ const [${varName}] = $t(${elVar}, '${text.slotId}')`)
+  }
   lines.push(`${indent}if (${varName}) createEffect(() => { ${varName}.textContent = String(${text.wrappedExpression}) }${bfId}) }`)
 }