@barefootjs/jsx 0.18.5 → 0.18.7

package/src/adapters/dangerous-inner-html.ts

@@ -0,0 +1,186 @@
+/**
+ * Shared `dangerouslySetInnerHTML={{ __html: expr }}` recognition + policy
+ * (#2207). Single place every template adapter calls from `renderElement`,
+ * so the injection-safety-relevant policy — "only a compile-time string
+ * literal is lowered; anything else refuses loudly" — lives in exactly one
+ * reviewable spot instead of being re-derived independently in 8 adapters.
+ *
+ * Scope, deliberately narrow for v1 (see #2207 / #2215 for the follow-up):
+ * a static literal is spliced directly into the adapter's OWN template
+ * source as trusted text (same trust domain as hand-writing the HTML into
+ * the template) — never routed through a `|safe`/`|raw`/`{!! !!}`-style
+ * runtime raw-output primitive, which would reopen a template-source
+ * injection surface for no benefit (the value is already fully known at
+ * compile time). A DYNAMIC value (signal, prop, a template literal WITH a
+ * substitution, local const, anything non-literal) is refused with
+ * `BF101` — a no-substitution template literal is NOT dynamic; the parser
+ * normalizes it to the same `{kind:'literal', literalType:'string'}` shape
+ * as a plain string literal, so it's treated identically (see
+ * `staticHtmlLiteral` below). Hono/CSR already support it (the client
+ * drives a `createEffect`-based `el.innerHTML = …`
+ * assignment — see `ir-to-client-js/emit-reactive.ts`), so this is a
+ * template-adapter-only gap, tracked separately (#2215) rather than folded
+ * into this literal-only cut.
+ */
+
+import type { CompilerError, IRAttribute, IRElement, SourceLocation } from '../types.ts'
+import { parseExpression, type ParsedExpr } from '../expression-parser.ts'
+
+const DANGEROUS_INNER_HTML_ATTR = 'dangerouslySetInnerHTML'
+
+export function isDangerousInnerHtmlAttr(attr: IRAttribute): boolean {
+  return attr.name === DANGEROUS_INNER_HTML_ATTR
+}
+
+export type DangerousInnerHtmlResolution =
+  | { kind: 'static'; html: string }
+  | { kind: 'dynamic'; expr: string; loc: SourceLocation }
+
+/**
+ * Resolve `element`'s `dangerouslySetInnerHTML` attribute, if present.
+ * Returns `null` when the attribute is absent (the overwhelmingly common
+ * case — callers should treat `null` as "render this element normally") —
+ * or when it carries `/* @client *\/` (Fable review, #2217): a `clientOnly`
+ * attr is already deferred to hydrate by every adapter's `renderAttributes`
+ * (`if (attr.clientOnly) continue`, unrelated to this module), which is
+ * itself a working escape hatch for a dynamic `__html` — the client's
+ * `createEffect`-driven `el.innerHTML = …` assignment (`emit-reactive.ts`)
+ * runs regardless of what SSR does. Treating `clientOnly` as "render this
+ * element normally" here (rather than refusing with BF101) preserves that
+ * escape hatch instead of regressing it.
+ * A present-but-non-`expression` value (e.g. a bare boolean/spread — not a
+ * shape `{ __html }` can ever legitimately take) is treated as `dynamic`
+ * so it refuses rather than silently doing nothing.
+ */
+export function resolveDangerousInnerHtml(element: IRElement): DangerousInnerHtmlResolution | null {
+  const attr = element.attrs.find(isDangerousInnerHtmlAttr)
+  if (!attr) return null
+  if (attr.clientOnly) return null
+  if (attr.value.kind !== 'expression') {
+    return { kind: 'dynamic', expr: '', loc: attr.loc }
+  }
+  const parsed = attr.value.parsed ?? parseExpression(attr.value.expr.trim())
+  const html = staticHtmlLiteral(parsed)
+  if (html !== null) return { kind: 'static', html }
+  return { kind: 'dynamic', expr: attr.value.expr, loc: attr.loc }
+}
+
+/**
+ * `{ __html: '<b>bold</b>' }` → the literal string, nothing else. Exactly
+ * one property, key `__html` (identifier or string form — `{ __html: … }`
+ * and `{ '__html': … }` are equivalent JS), non-shorthand (`{ __html }`
+ * would read a variable, not a literal), value a compile-time STRING
+ * LITERAL `ParsedExpr` (`{kind:'literal', literalType:'string'}`) — which
+ * a no-substitution template literal (`` `<b>bold</b>` ``) already parses
+ * to, so it's accepted the same as a quoted string. A template literal
+ * WITH a substitution, a local `const`, string concatenation, or any other
+ * non-literal shape all fall through to `null` — no const-folding, no
+ * partial evaluation. Widening this is a single-place change here,
+ * deliberately not attempted in v1 (#2207).
+ */
+function staticHtmlLiteral(parsed: ParsedExpr): string | null {
+  if (parsed.kind !== 'object-literal') return null
+  if (parsed.properties.length !== 1) return null
+  const [prop] = parsed.properties
+  if (prop.shorthand) return null
+  if (prop.key !== '__html') return null
+  if (prop.value.kind !== 'literal' || prop.value.literalType !== 'string') return null
+  return prop.value.value as string
+}
+
+/**
+ * Per-adapter template-metacharacter guard for the STATIC-literal path.
+ * The literal is spliced into the adapter's own template source as plain
+ * text — safe against HTML injection (it's the developer's own compile-time
+ * string, same trust boundary as writing the HTML by hand), but NOT
+ * automatically safe against TEMPLATE-source injection: a literal
+ * containing `{{ … }}` (Go/Jinja/minijinja/Twig), `<% … %>` (ERB/
+ * Mojolicious), `{!! !!}`/`@directive`/`<?php`/`<x-…>` (Blade — the last is
+ * Laravel's component-tag syntax, on by default; see below), or `<: … :>`
+ * (Xslate) would be interpreted as a live template construct instead of
+ * inert text once spliced in. Mojolicious and Xslate also support
+ * whole-line "line code" (a line starting with `%`/`:`, possibly indented —
+ * `\s` covers the same whitespace class Mojo::Template/Xslate strip),
+ * checked with `m`. Refuses (via {@link dangerousInnerHtmlDiagnostic})
+ * rather than escaping — escaping a supposedly-raw-HTML literal would
+ * silently corrupt the developer's own markup, which is worse than a loud
+ * compile-time refusal.
+ *
+ * Blade's `<x-…>`/`</x-…>`: this project's `BladeBackend` constructs a
+ * plain `Illuminate\View\Compilers\BladeCompiler`, whose component-tag
+ * compiler (`$compilesComponentTags = true` by default) resolves and
+ * renders a live Blade component for `<x-foo>` — NOT template-substitution,
+ * full component-class/view resolution (Fable review, #2217). This is the
+ * single sharpest case of "not inert text once spliced" in the whole guard
+ * table, sharper than a bare `{{ }}` interpolation.
+ *
+ * Go's `html/template` context-aware escaper is a DOCUMENTED caveat, not a
+ * guarded case: it parses the spliced literal to pick escaping contexts for
+ * SUBSEQUENT `{{ }}` actions in the same template, so malformed markup (an
+ * unclosed `<script>`/`<style>`) can produce a template `Parse` error or
+ * mis-contexted escaping of later actions — output corruption, never
+ * injection, and no different from hand-writing the same malformed HTML
+ * into the template (this module's stated trust domain). The `{{` guard
+ * below still catches the actual injection vector (a literal containing a
+ * live action).
+ */
+const TEMPLATE_METACHAR_PATTERNS: Readonly<Record<string, RegExp>> = {
+  blade: /\{\{|\{!!|<\?|@\w|<\/?\s*x[-:]/,
+  erb: /<%/,
+  'go-template': /\{\{/,
+  jinja: /\{\{|\{%|\{#/,
+  minijinja: /\{\{|\{%|\{#/,
+  mojolicious: /<%|^\s*%/m,
+  twig: /\{\{|\{%|\{#/,
+  xslate: /<:|^\s*:/m,
+}
+
+/**
+ * `null` when `html` is safe to splice as-is into `adapterId`'s template
+ * source; otherwise a human-readable reason naming the offending adapter's
+ * metacharacter family (or the missing-guard case below), for the refusal
+ * message.
+ *
+ * FAILS CLOSED for an `adapterId` with no entry in
+ * {@link TEMPLATE_METACHAR_PATTERNS} (Fable review, #2217): a 9th template
+ * adapter added later — e.g. by following the repo's own `add-adapter`
+ * playbook, which will tell it to wire the same
+ * `resolveDangerousInnerHtml`/`dangerousInnerHtmlMetacharViolation` calls
+ * every existing adapter does — must not silently get an unguarded splice
+ * just because nobody remembered to extend this table. Refusing loudly is
+ * the safe default; only the 8 adapters actually verified against their
+ * own template compiler's syntax get to skip the refusal.
+ */
+export function dangerousInnerHtmlMetacharViolation(html: string, adapterId: string): string | null {
+  const pattern = TEMPLATE_METACHAR_PATTERNS[adapterId]
+  if (!pattern) {
+    return `no template-metacharacter guard is defined for adapter '${adapterId}' — refusing rather than splicing unguarded`
+  }
+  if (!pattern.test(html)) return null
+  return `the literal HTML contains a sequence ${adapterId}'s own template compiler would interpret (not inert text once spliced into the template)`
+}
+
+/**
+ * Purpose-built `BF101` for a `dangerouslySetInnerHTML` value this adapter
+ * can't lower — either genuinely dynamic (not a literal) or a static
+ * literal that fails the metachar guard above. Named `reason` so both
+ * refusal paths funnel through the same message shape rather than growing
+ * two near-identical adapter-side error strings.
+ */
+export function dangerousInnerHtmlDiagnostic(
+  expr: string,
+  loc: SourceLocation,
+  reason?: string,
+): CompilerError {
+  const detail = reason ? ` — ${reason}.` : ''
+  return {
+    code: 'BF101',
+    severity: 'error',
+    message: `dangerouslySetInnerHTML requires a compile-time string literal __html value on template adapters (e.g. { __html: '...' })${expr ? `: ${expr.trim()}` : ''}${detail}`,
+    loc,
+    suggestion: {
+      message:
+        'Dynamic or signal-derived HTML for dangerouslySetInnerHTML is only supported on Hono/CSR today (tracked separately: https://github.com/piconic-ai/barefootjs/issues/2215). Use an inline string literal, or defer it to the client with /* @client */ (e.g. dangerouslySetInnerHTML={/* @client */ { __html: expr }}) so hydration sets it instead of SSR.',
+    },
+  }
+}

package/src/adapters/loop-bound-names.ts

@@ -0,0 +1,80 @@
+/**
+ * Every name a `.map()`/`.filter()` loop callback binds as its item or
+ * index parameter, anywhere in a component's IR tree (#2212 review
+ * finding). `isStringTypedOperand`'s identifier arm resolves a bare
+ * identifier against `collectStringValueNames`'s flat, scope-BLIND
+ * `Set<string>` — so a loop callback whose param happens to reuse a
+ * string prop's name (`items.map((name) => ... 1 + name ...)`, where the
+ * component also has a string `name` prop) would otherwise be
+ * misdetected as string-typed, silently lowering a NUMERIC `+` to the
+ * adapter's string-concat operator instead of leaving it numeric — wrong
+ * rendered output, not a refusal. Subtracting every loop-bound name from
+ * the string-name set (in each adapter's `collectStringValueNames`) is a
+ * coarse but SAFE mitigation: a name used as a loop param anywhere in the
+ * component never gets string-concat treatment anywhere in the
+ * component, even at a non-shadowed use site outside that loop — which
+ * degrades to the ALREADY-accepted residual (`+` falls back to numeric,
+ * same as before #2212 for an unresolvable operand) rather than ever
+ * producing silently-wrong output.
+ */
+
+import type { ComponentIR, IRNode } from '../types.ts'
+
+export function collectLoopBoundNames(ir: ComponentIR): Set<string> {
+  const names = new Set<string>()
+  const visit = (node: IRNode | null | undefined): void => {
+    if (!node) return
+    switch (node.type) {
+      case 'element':
+      case 'component':
+      case 'fragment':
+      case 'provider':
+        for (const child of node.children) visit(child)
+        break
+      case 'async':
+        visit(node.fallback)
+        for (const child of node.children) visit(child)
+        break
+      case 'loop':
+        names.add(node.param)
+        if (node.index) names.add(node.index)
+        // A destructured callback param (`.map(({ name }) => ...)`) binds
+        // its extracted names via `paramBindings`, not `param` itself
+        // (`param` holds the raw pattern text there) — adapters that lower
+        // the destructure to a `{% set name = __bf_item.name %}`-style
+        // local (#2087) leave `name` reachable as a bare identifier in the
+        // body, so it needs the same exclusion as a plain loop param.
+        for (const binding of node.paramBindings ?? []) names.add(binding.name)
+        // A `.filter(pred).map(cb)` chain's filter predicate is emitted
+        // through the same binary/string-name machinery, using its OWN
+        // param (which may differ from the map callback's `param`) before
+        // any rename to the loop param happens.
+        if (node.filterPredicate) names.add(node.filterPredicate.param)
+        for (const child of node.children) visit(child)
+        if (node.childComponent) {
+          for (const child of node.childComponent.children) visit(child)
+        }
+        for (const nested of node.nestedComponents ?? []) {
+          for (const child of nested.children) visit(child)
+        }
+        for (const frag of node.flatMapCallback?.fragments ?? []) {
+          visit(frag.ir)
+        }
+        break
+      case 'conditional':
+        visit(node.whenTrue)
+        visit(node.whenFalse)
+        break
+      case 'if-statement':
+        visit(node.consequent)
+        if (node.alternate) visit(node.alternate)
+        break
+      case 'text':
+      case 'expression':
+      case 'slot':
+        break
+    }
+  }
+  visit(ir.root)
+  return names
+}

package/src/adapters/parsed-expr-emitter.ts

@@ -228,6 +228,15 @@ export function isStringTypedOperand(expr: ParsedExpr, isStringName: (n: string)
   if (expr.kind === 'member' && expr.object.kind === 'identifier' && expr.object.name === 'props') {
     return isStringName(expr.property)
   }
+  // A bare identifier (#2212): a destructured prop param or a same-file
+  // local const, string-typed per the caller's `isStringName` set — each
+  // adapter's `collectStringValueNames` already tracks `propsParams`, so a
+  // component's own `{ a, b }: { a: string; b: string }` destructure was
+  // only unreachable here for lack of this arm; extending
+  // `collectStringValueNames` to also walk `ir.metadata.localConstants`
+  // (adapter-side change) closes the "two same-file string consts" shape
+  // the same way.
+  if (expr.kind === 'identifier') return isStringName(expr.name)
   if (expr.kind === 'binary' && expr.op === '+') {
     return isStringTypedOperand(expr.left, isStringName) || isStringTypedOperand(expr.right, isStringName)
   }

package/src/analyzer.ts

@@ -50,6 +50,11 @@ export function needsTypeBasedDetection(source: string): boolean {
   if (REACTIVE_BRAND_PACKAGES.some(pkg => source.includes(pkg))) return true
   // BF023/BF024 nullable-key check needs getTypeAtLocation() on the key expression.
   if (/\.map\s*\(/.test(source)) return true
+  // createSelector's returned accessor is Reactive<>-branded like a library
+  // accessor above — a selector call outside any `.map()` (no loop in the
+  // file at all) would otherwise skip the TypeChecker entirely and miss the
+  // brand.
+  if (source.includes('createSelector')) return true
   return false
 }
 
@@ -1828,6 +1833,7 @@ function collectLocalDeclarations(root: ts.Node): Set<string> {
 // and are emitted by the compiler for 'use client' components.
 const CLIENT_EXPORTS = new Set([
   'createSignal', 'createEffect', 'createDisposableEffect', 'createMemo',
+  'createSelector',
   'createRoot', 'onCleanup', 'onMount', 'untrack', 'batch', 'splitProps',
   'forwardProps', 'unwrap', '__slot',
   'createContext', 'useContext', 'provideContext',

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[]
 }

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
   /**