@barefootjs/jsx 0.18.4 → 0.18.7

package/src/__tests__/create-selector.test.ts

@@ -0,0 +1,110 @@
+/**
+ * `createSelector` compiler recognition (perf, #2143 gap 5).
+ *
+ * `createSelector`'s returned accessor is `Reactive<(key) => boolean>`
+ * branded exactly like a signal/memo getter, so the existing type-based
+ * reactivity analyzer (`reactivity-checker.ts`) recognises a call like
+ * `isSelected(row.id)` as reactive with no analyzer changes — the callee's
+ * type carries the brand, not the call's return type. These tests pin:
+ *   - the classic js-framework-benchmark row compiles with `isSelected(row.id)`
+ *     wired to a single per-row `createEffect` (not the legacy
+ *     `selected() === row.id` shape, which would still work but subscribes
+ *     every row to the raw signal)
+ *   - the loop-param accessor wrap applies only to the call ARGUMENT
+ *     (`row.id` -> `row().id`), leaving the `isSelected` callee untouched
+ *   - the hoisted skeleton fast path (#2223) still fires for a selector-driven
+ *     attr, since it's covered by a loop-child reactive-attr effect like any
+ *     other dynamic attribute
+ *   - `createSelector` is pulled into the runtime import line
+ *   - the attr is auto-deferred out of the SSR-mirror `template:` lambda
+ *     (mechanism #1638, same as `@barefootjs/form` accessors) — pinned as
+ *     documented behavior, not a regression: full SSR parity for selector
+ *     calls is a known follow-up, not in scope here
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+function compile(source: string, filename: string): { clientJs: string; template: string; errors: readonly { severity: string }[] } {
+  const result = compileJSX(source, filename, { adapter })
+  const clientJs = result.files.find(f => f.type === 'clientJs')
+  const template = result.files.find(f => f.type === 'markedTemplate')
+  return { clientJs: clientJs?.content ?? '', template: template?.content ?? '', errors: result.errors }
+}
+
+describe('createSelector (perf, #2143 gap 5)', () => {
+  test('isSelected(row.id) in a loop body compiles to one per-row createEffect', () => {
+    const source = `
+      'use client'
+      import { createSignal, createSelector } from '@barefootjs/client'
+
+      interface RowData { id: number; label: string }
+
+      export function Bench() {
+        const [rows, setRows] = createSignal<RowData[]>([])
+        const [selected, setSelected] = createSignal<number>(0)
+        const isSelected = createSelector(selected)
+        return (
+          <table>
+            <tbody>
+              {rows().map(row => (
+                <tr key={row.id} className={isSelected(row.id) ? 'danger' : ''}></tr>
+              ))}
+            </tbody>
+          </table>
+        )
+      }
+    `
+    const { clientJs, errors } = compile(source, 'Bench.tsx')
+    expect(errors.filter(e => e.severity === 'error')).toHaveLength(0)
+
+    // Loop-param wrap applies to the call ARGUMENT only.
+    expect(clientJs).toContain('isSelected(row().id)')
+    // The callee itself is never rewritten to an accessor call.
+    expect(clientJs).not.toContain('isSelected()(')
+
+    // Exactly one createEffect wraps the selector-driven class attribute —
+    // not the O(rows) `selected() === row.id` shape.
+    const effectCount = (clientJs.match(/createEffect\(/g) ?? []).length
+    expect(effectCount).toBe(1)
+    expect(clientJs).not.toContain('selected() ===')
+
+    // The hoisted skeleton fast path (#2223) still fires: a single-line
+    // renderItem clones from a once-per-loop template.
+    expect(clientJs).toMatch(/const __tpl_\w+ = document\.createElement\('template'\)/)
+
+    // createSelector is pulled into the runtime import line.
+    expect(clientJs).toMatch(/import \{[^}]*\bcreateSelector\b[^}]*\} from '@barefootjs\/client\/runtime'/)
+  })
+
+  test('selector-driven attr is deferred out of the SSR-mirror template lambda (documented, not a regression)', () => {
+    const source = `
+      'use client'
+      import { createSignal, createSelector } from '@barefootjs/client'
+
+      interface RowData { id: number; label: string }
+
+      export function Bench() {
+        const [rows, setRows] = createSignal<RowData[]>([])
+        const [selected, setSelected] = createSignal<number>(0)
+        const isSelected = createSelector(selected)
+        return (
+          <ul>
+            {rows().map(row => (
+              <li key={row.id} className={isSelected(row.id) ? 'danger' : ''}>{row.label}</li>
+            ))}
+          </ul>
+        )
+      }
+    `
+    const { clientJs } = compile(source, 'BenchDefer.tsx')
+    const csrMirror = clientJs.slice(clientJs.indexOf('hydrate('))
+    // The class attribute never appears as a literal `class="..."` write in
+    // the SSR-mirror template string — it's covered entirely by the
+    // per-row createEffect, matching the documented auto-defer mechanism.
+    expect(csrMirror).not.toMatch(/class="danger"/)
+  })
+})

package/src/__tests__/csr-template-loop-shadowing.test.ts

@@ -0,0 +1,214 @@
+/**
+ * CSR/client-JS codegen vs loop-param shadowing (#2222).
+ *
+ * Two related bugs in the `hydrate(...)` `template:` lambda (a
+ * module-scope arrow, sibling to `initXxx` — NOT a closure over init's
+ * destructured locals):
+ *
+ * 1. When the loop's array source is a destructured prop, the lambda
+ *    referenced the bare destructured name (`values.map(...)`) instead of
+ *    `_p.values` — `ReferenceError: values is not defined` at runtime.
+ *    Root cause: `transformMapCall`'s plain-`.map()` fallback and the
+ *    simple-`filter().map()` path bypassed `setArray`, so
+ *    `IRLoop.templateArray` (the `_p.`-rewritten form the chained paths
+ *    already produce) stayed `undefined`.
+ *
+ * 2. Inside a loop callback body in that same lambda, prop/const
+ *    substitution was scope-blind: an outer destructured prop
+ *    (`_p.label`) or an inlinable const's literal got substituted at an
+ *    occurrence that is actually the loop's own shadowing parameter.
+ *    Same bug class as #2221, different code paths:
+ *      - prop-shadow: `rewriteBarePropRefs` (IR build) collected prop
+ *        refs from the expression node alone, never seeing the enclosing
+ *        loop binding. Fixed scope-accurately via `ctx.loopParams` — the
+ *        transform position's live loop-param set (includes destructured
+ *        binding names and the index param).
+ *      - const-shadow: `irToComponentTemplateWithOpts`'s `transformExpr`
+ *        regex-inlined `inlinableConstants` across the whole expression
+ *        text. Fixed by threading the enclosing loops' bound names
+ *        through `TemplateOptions` and skipping those names.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+function clientJsFor(source: string): string {
+  const result = compileJSX(source, 'Repro.tsx', { adapter })
+  expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+  const clientJs = result.files.find(f => f.type === 'clientJs')
+  expect(clientJs).toBeDefined()
+  return clientJs!.content
+}
+
+function templateLambda(content: string): string {
+  const line = content.split('\n').find(l => l.includes('hydrate('))
+  expect(line).toBeDefined()
+  return line!
+}
+
+describe('hydrate template: destructured-prop loop array source (#2222 bug 1)', () => {
+  test('plain .map() over a destructured prop references _p.<name>', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget({ values }: { values: number[] }) {
+        const [n, setN] = createSignal(0)
+        return (
+          <ul data-n={n()} onClick={() => setN(n() + 1)}>
+            {values.map((v) => (
+              <li key={v}>{v * 2}</li>
+            ))}
+          </ul>
+        )
+      }
+    `))
+
+    expect(tpl).toContain('_p.values.map((v)')
+    expect(tpl).not.toContain('{values.map')
+  })
+
+  test('simple filter().map() over a destructured prop references _p.<name>', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget({ values }: { values: number[] }) {
+        const [n, setN] = createSignal(0)
+        return (
+          <ul data-n={n()} onClick={() => setN(n() + 1)}>
+            {values.filter((v) => v > 0).map((v) => (
+              <li key={v}>{v * 2}</li>
+            ))}
+          </ul>
+        )
+      }
+    `))
+
+    expect(tpl).toContain('_p.values')
+    expect(tpl).not.toMatch(/[^.]\bvalues\.filter/)
+  })
+})
+
+describe('hydrate template: loop param shadowing an outer name (#2222 bug 2)', () => {
+  test('prop-shadow: the loop body uses the param, not _p.<name>; outside the loop keeps _p.<name>', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget2({ label, values }: { label: string; values: number[] }) {
+        const [n, setN] = createSignal(0)
+        return (
+          <div data-n={n()} onClick={() => setN(n() + 1)}>
+            <p>{label}</p>
+            <ul>
+              {values.map((label) => (
+                <li key={label}>{1 + label}</li>
+              ))}
+            </ul>
+          </div>
+        )
+      }
+    `))
+
+    // Outside the loop: the prop rewrite applies.
+    expect(tpl).toContain('escapeText(_p.label)')
+    // Inside the loop: the shadowing param must survive untouched.
+    expect(tpl).toContain('escapeText(1 + label)')
+    expect(tpl).not.toContain('1 + _p.label')
+    expect(tpl).not.toContain('data-key="${_p.label}"')
+  })
+
+  test('const-shadow: the loop body uses the param, not the inlined literal; outside the loop keeps the inline', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget3({ values }: { values: number[] }) {
+        const label: string = 'x'
+        const [n, setN] = createSignal(0)
+        return (
+          <div data-n={n()} onClick={() => setN(n() + 1)}>
+            <p>{label}</p>
+            <ul>
+              {values.map((label) => (
+                <li key={label}>{1 + label}</li>
+              ))}
+            </ul>
+          </div>
+        )
+      }
+    `))
+
+    // Outside the loop: const inlining still applies.
+    expect(tpl).toContain("${('x')}")
+    // Inside the loop: the shadowing param must survive untouched.
+    expect(tpl).toContain('escapeText(1 + label)')
+    expect(tpl).not.toContain("1 + ('x')")
+    expect(tpl).not.toContain('data-key="${`x`}"')
+  })
+
+  test('destructured loop param shadowing a prop is guarded via paramBindings names', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget4({ name, rows }: { name: string; rows: { name: number }[] }) {
+        const [n, setN] = createSignal(0)
+        return (
+          <ul data-n={n()} onClick={() => setN(n() + 1)}>
+            {rows.map(({ name }) => (
+              <li key={name}>{1 + name}</li>
+            ))}
+          </ul>
+        )
+      }
+    `))
+
+    expect(tpl).not.toContain('1 + _p.name')
+  })
+
+  test('a Unicode loop param shadowing a const is still guarded (#2238 Copilot review)', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget6({ values }: { values: number[] }) {
+        const \u03c0: string = 'x'
+        const [n, setN] = createSignal(0)
+        return (
+          <div data-n={n()} onClick={() => setN(n() + 1)}>
+            <p>{\u03c0}</p>
+            <ul>
+              {values.map((\u03c0) => (
+                <li key={\u03c0}>{1 + \u03c0}</li>
+              ))}
+            </ul>
+          </div>
+        )
+      }
+    `))
+
+    // The Unicode param must be recognised as a bare identifier (not a
+    // destructure pattern), so the const never substitutes in the body.
+    expect(tpl).toContain('1 + \u03c0')
+    expect(tpl).not.toContain("1 + ('x')")
+  })
+
+  test('a non-shadowing prop used inside the loop still rewrites to _p.<name>', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget5({ prefix, values }: { prefix: string; values: number[] }) {
+        const [n, setN] = createSignal(0)
+        return (
+          <ul data-n={n()} onClick={() => setN(n() + 1)}>
+            {values.map((v) => (
+              <li key={v}>{prefix + v}</li>
+            ))}
+          </ul>
+        )
+      }
+    `))
+
+    // A prop NOT shadowed by the loop param keeps its rewrite inside the body.
+    expect(tpl).toContain('_p.prefix + v')
+  })
+})

package/src/__tests__/dangerous-inner-html-resolver.test.ts

@@ -0,0 +1,197 @@
+import { describe, test, expect } from 'bun:test'
+import { analyzeComponent } from '../analyzer'
+import { jsxToIR } from '../jsx-to-ir'
+import {
+  isDangerousInnerHtmlAttr,
+  resolveDangerousInnerHtml,
+  dangerousInnerHtmlMetacharViolation,
+  dangerousInnerHtmlDiagnostic,
+} from '../adapters/dangerous-inner-html'
+
+// #2207: the shared `dangerouslySetInnerHTML` resolver — recognition,
+// static-literal extraction, and per-adapter template-metacharacter
+// guarding all live in one place (packages/jsx/src/adapters/dangerous-inner-html.ts)
+// so every template adapter shares identical, single-source-of-truth policy.
+describe('resolveDangerousInnerHtml (#2207)', () => {
+  function rootElement(source: string) {
+    const ctx = analyzeComponent(source, 'Test.tsx')
+    const ir = jsxToIR(ctx)
+    if (!ir || ir.type !== 'element') throw new Error('expected a root element')
+    return ir
+  }
+
+  test('absent attribute resolves to null', () => {
+    const el = rootElement(`
+      function Test() { return <div>hi</div> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)).toBeNull()
+  })
+
+  test('inline string literal resolves as static', () => {
+    const el = rootElement(`
+      function Test() { return <div dangerouslySetInnerHTML={{ __html: '<b>bold</b> &amp; safe' }} /> }
+      export { Test }
+    `)
+    const resolution = resolveDangerousInnerHtml(el)
+    expect(resolution).toEqual({ kind: 'static', html: '<b>bold</b> &amp; safe' })
+  })
+
+  test('string-key form ({ "__html": ... }) resolves identically to the identifier-key form', () => {
+    const el = rootElement(`
+      function Test() { return <div dangerouslySetInnerHTML={{ '__html': '<i>x</i>' }} /> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)).toEqual({ kind: 'static', html: '<i>x</i>' })
+  })
+
+  test('signal/prop-derived value resolves as dynamic', () => {
+    const el = rootElement(`
+      function Test({ html }: { html: string }) { return <div dangerouslySetInnerHTML={{ __html: html }} /> }
+      export { Test }
+    `)
+    const resolution = resolveDangerousInnerHtml(el)
+    expect(resolution?.kind).toBe('dynamic')
+  })
+
+  test('a no-substitution template literal resolves as static (identical to a string literal)', () => {
+    const el = rootElement(`
+      function Test() { return <div dangerouslySetInnerHTML={{ __html: \`<b>bold</b>\` }} /> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)).toEqual({ kind: 'static', html: '<b>bold</b>' })
+  })
+
+  test('a template literal WITH a substitution resolves as dynamic — no const-folding in v1', () => {
+    const el = rootElement(`
+      function Test({ tag }: { tag: string }) { return <div dangerouslySetInnerHTML={{ __html: \`<\${tag}>bold</\${tag}>\` }} /> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)?.kind).toBe('dynamic')
+  })
+
+  test('shorthand { __html } resolves as dynamic, not the literal named __html', () => {
+    const el = rootElement(`
+      function Test({ __html }: { __html: string }) { return <div dangerouslySetInnerHTML={{ __html }} /> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)?.kind).toBe('dynamic')
+  })
+
+  test('local const reference resolves as dynamic — v1 requires an INLINE literal', () => {
+    const el = rootElement(`
+      const HTML = '<b>bold</b>'
+      function Test() { return <div dangerouslySetInnerHTML={{ __html: HTML }} /> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)?.kind).toBe('dynamic')
+  })
+
+  test('extra property alongside __html resolves as dynamic', () => {
+    const el = rootElement(`
+      function Test() { return <div dangerouslySetInnerHTML={{ __html: '<b>x</b>', extra: 1 }} /> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)?.kind).toBe('dynamic')
+  })
+
+  test('isDangerousInnerHtmlAttr only matches the exact prop name', () => {
+    const el = rootElement(`
+      function Test() { return <div data-foo="bar" dangerouslySetInnerHTML={{ __html: 'x' }} /> }
+      export { Test }
+    `)
+    const names = el.attrs.map(a => a.name)
+    expect(names.filter(n => isDangerousInnerHtmlAttr({ name: n } as never))).toEqual(['dangerouslySetInnerHTML'])
+  })
+
+  // Fable review (#2217): a `/* @client */`-deferred value is already a
+  // working escape hatch — every adapter's own renderAttributes skips a
+  // clientOnly attr, and the client's createEffect-driven innerHTML
+  // assignment (emit-reactive.ts) runs regardless of SSR — so this module
+  // must treat it as "render normally" (null), not refuse with BF101.
+  // Refusing here was a real regression the review caught: it broke the
+  // only path that made this module's own suggestion text achievable.
+  test('/* @client */-deferred dangerouslySetInnerHTML resolves to null (render normally, defer to hydrate)', () => {
+    const el = rootElement(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function Test() {
+        const [html, setHtml] = createSignal('<b>hi</b>')
+        return <div dangerouslySetInnerHTML={/* @client */ { __html: html() }} />
+      }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)).toBeNull()
+  })
+
+  test('empty-string literal resolves as static with an empty html value', () => {
+    const el = rootElement(`
+      function Test() { return <div dangerouslySetInnerHTML={{ __html: '' }} /> }
+      export { Test }
+    `)
+    expect(resolveDangerousInnerHtml(el)).toEqual({ kind: 'static', html: '' })
+  })
+})
+
+describe('dangerousInnerHtmlMetacharViolation (#2207)', () => {
+  test('plain HTML is safe on every adapter', () => {
+    for (const id of ['blade', 'erb', 'go-template', 'jinja', 'minijinja', 'mojolicious', 'twig', 'xslate']) {
+      expect(dangerousInnerHtmlMetacharViolation('<b>bold</b> &amp; safe', id)).toBeNull()
+    }
+  })
+
+  // Fable review (#2217): a 9th template adapter with no entry in the guard
+  // table must fail CLOSED (refuse) rather than fail open (splice
+  // unguarded) — the safe default when nobody has verified that adapter's
+  // template syntax yet.
+  test('unknown adapter id fails CLOSED (refuses) rather than open', () => {
+    expect(dangerousInnerHtmlMetacharViolation('<b>plain html, no metachars</b>', 'not-a-real-adapter')).not.toBeNull()
+  })
+
+  const cases: Array<[adapterId: string, html: string]> = [
+    ['blade', '<b>{{ $evil }}</b>'],
+    ['blade', '<b>{!! $evil !!}</b>'],
+    ['blade', '<?php echo 1; ?>'],
+    ['blade', '@if(true)x@endif'],
+    // Laravel's BladeCompiler compiles component tags by default — <x-foo>
+    // resolves and renders a live Blade component, not template
+    // substitution. The sharpest "not inert text" case in the table.
+    ['blade', '<x-alert>evil</x-alert>'],
+    ['blade', '</x-alert>'],
+    ['erb', '<b><%= evil %></b>'],
+    ['go-template', '<b>{{ .Evil }}</b>'],
+    ['jinja', '<b>{{ evil }}</b>'],
+    ['jinja', '<b>{% if x %}y{% endif %}</b>'],
+    ['jinja', '<b>{# comment #}</b>'],
+    ['minijinja', '<b>{{ evil }}</b>'],
+    ['twig', '<b>{{ evil }}</b>'],
+    ['mojolicious', '<b><%= evil %></b>'],
+    ['mojolicious', '% my $x = 1;\n<b>hi</b>'],
+    // Leading whitespace (not just a bare line start) before the line-code
+    // marker, and the marker as the very first character of the string.
+    ['mojolicious', '  % my $x = 1;\n<b>hi</b>'],
+    ['mojolicious', '% my $x = 1;'],
+    ['xslate', '<b><: $evil :></b>'],
+    ['xslate', ': my $x = 1;\n<b>hi</b>'],
+    ['xslate', '  : my $x = 1;\n<b>hi</b>'],
+    ['xslate', ': my $x = 1;'],
+    // A literal that IS only the metachar sequence, nothing else.
+    ['blade', '{{'],
+    ['go-template', '{{'],
+  ]
+  for (const [adapterId, html] of cases) {
+    test(`${adapterId} refuses ${JSON.stringify(html)}`, () => {
+      expect(dangerousInnerHtmlMetacharViolation(html, adapterId)).not.toBeNull()
+    })
+  }
+})
+
+describe('dangerousInnerHtmlDiagnostic (#2207)', () => {
+  test('produces a BF101 with a purpose-built message', () => {
+    const diag = dangerousInnerHtmlDiagnostic('html', { file: 'Test.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } })
+    expect(diag.code).toBe('BF101')
+    expect(diag.severity).toBe('error')
+    expect(diag.message).toContain('dangerouslySetInnerHTML requires a compile-time string literal')
+    expect(diag.suggestion?.message).toContain('2215')
+  })
+})

package/src/__tests__/event-delegation-index-param.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Delegated handlers closing over the `.map((item, i) => ...)` index param
+ * (#2189). The dispatcher re-derives the index at dispatch time and binds it
+ * under the user's name, so a handler like `() => handle(i)` no longer throws
+ * `ReferenceError: i is not defined`. Gating is byte-for-byte free of churn
+ * when the handler doesn't reference the index.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+function clientJsFor(source: string): string {
+  const result = compileJSX(source, 'Repro.tsx', { adapter })
+  expect(result.errors).toHaveLength(0)
+  const clientJs = result.files.find(f => f.type === 'clientJs')
+  expect(clientJs).toBeDefined()
+  return clientJs!.content
+}
+
+describe('delegated handler closing over the .map() index (#2189)', () => {
+  test('keyed loop: index is re-derived via findIndex and bound', () => {
+    const content = clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      interface Item { id: number; label: string }
+      export function Repro() {
+        const [items] = createSignal<Item[]>([])
+        const handle = (index: number) => { console.log(index) }
+        return (
+          <ul>
+            {items().map((item, i) => (
+              <li key={item.id}>
+                <button onClick={() => handle(i)}>{item.label}</button>
+              </li>
+            ))}
+          </ul>
+        )
+      }
+    `)
+
+    // The index param `i` must be bound inside the delegation dispatcher.
+    expect(content).toContain('const i = items().findIndex(item => String(item.id) === key)')
+    // ...and the handler is still invoked with the synthetic event.
+    expect(content).toContain('(() => handle(i))(__bfEvt)')
+    // No dangling reference: `i` is declared before the handler call runs.
+    const idxDecl = content.indexOf('const i = items().findIndex')
+    const idxCall = content.indexOf('handle(i))(__bfEvt)')
+    expect(idxDecl).toBeGreaterThanOrEqual(0)
+    expect(idxCall).toBeGreaterThan(idxDecl)
+  })
+
+  test('index binding is omitted when no handler references the index', () => {
+    const content = clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      interface Item { id: number; label: string }
+      export function Repro() {
+        const [items] = createSignal<Item[]>([])
+        const handle = (id: number) => { console.log(id) }
+        return (
+          <ul>
+            {items().map((item, i) => (
+              <li key={item.id}>
+                <button onClick={() => handle(item.id)}>{item.label}</button>
+              </li>
+            ))}
+          </ul>
+        )
+      }
+    `)
+
+    // Nothing references `i`, so the dispatcher must not emit an index binding.
+    expect(content).not.toContain('const i = items().findIndex')
+    expect(content).toContain('(() => handle(item.id))(__bfEvt)')
+  })
+
+  test('index named like a property is not bound when only the property is used', () => {
+    // Index param `id` shadows nothing here — the handler reads `item.id`, a
+    // property, not the index. Gating is AST-based (free identifiers), so no
+    // spurious binding is emitted.
+    const content = clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      interface Item { id: number; label: string }
+      export function Repro() {
+        const [items] = createSignal<Item[]>([])
+        const handle = (n: number) => { console.log(n) }
+        return (
+          <ul>
+            {items().map((item, id) => (
+              <li key={item.id}>
+                <button onClick={() => handle(item.id)}>{item.label}</button>
+              </li>
+            ))}
+          </ul>
+        )
+      }
+    `)
+
+    expect(content).not.toContain('.findIndex(')
+    expect(content).toContain('(() => handle(item.id))(__bfEvt)')
+  })
+
+  test('index param also works alongside item access in the same handler', () => {
+    const content = clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      interface Item { id: number; label: string }
+      export function Repro() {
+        const [items] = createSignal<Item[]>([])
+        const handle = (id: number, index: number) => { console.log(id, index) }
+        return (
+          <ul>
+            {items().map((item, i) => (
+              <li key={item.id}>
+                <button onClick={() => handle(item.id, i)}>{item.label}</button>
+              </li>
+            ))}
+          </ul>
+        )
+      }
+    `)
+
+    expect(content).toContain('const i = items().findIndex(item => String(item.id) === key)')
+    expect(content).toContain('handle(item.id, i))(__bfEvt)')
+  })
+})