@barefootjs/jsx 0.31.2 → 0.31.4

package/src/__tests__/csr-materialize-loop-preamble-shadow.test.ts

@@ -0,0 +1,76 @@
+/**
+ * #2482 Stage 1b — `generateCsrTemplateWithOpts`'s (`html-template.ts`)
+ * CSR "materialize" template lambda (the `hydrate(..., { template })`
+ * function used to render a loop's rows client-side with no SSR markup to
+ * hydrate against) const-folded a `.map()` callback preamble local (#2447)
+ * into an outer, same-named module-level const, instead of leaving the
+ * row-local binding unresolved.
+ *
+ * Root cause: the `loop` case's `opts.loopBoundNames` — a flat
+ * `Set<string>` re-unioned per recursion level — only ever accumulated
+ * the loop's item / index / destructured-binding names, never the
+ * callback's preamble-declared locals (#2447 postdates the original
+ * `loopBoundNames` shadow fix, #2222). Migrating onto `BindingScope`'s
+ * `enterLoopRow` (which binds item ∪ index ∪ destructure ∪ preamble
+ * `declaredNames` uniformly) closes the gap.
+ *
+ * Observable failure mode before the fix: every row's branch condition
+ * evaluated the constant's fixed truthiness instead of the row's own
+ * preamble-computed value — e.g. every `<li>` rendered its "true" branch
+ * regardless of the actual per-item condition.
+ *
+ * Modeled on `csr-template-loop-shadowing.test.ts` (the pre-#2447
+ * item/index/destructured-param shadowing pins for this same template
+ * lambda) and `binding-scope-preamble-shadowing.test.ts` (the IR-level
+ * preamble-shadowing analogue this test is the CSR-codegen-level sibling
+ * of).
+ */
+
+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('CSR materialize template vs .map() preamble-local shadowing a module const (#2482)', () => {
+  test('a preamble local shadowing a module const stays row-local in the hydrate template lambda', () => {
+    const tpl = templateLambda(clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget({ items }: { items: { name: string; active: boolean }[] }) {
+        const label = 'MODULE_CONST'
+        const [on, setOn] = createSignal(true)
+        return (
+          <div onClick={() => setOn(false)}>
+            <ul>
+              {items.map((item) => {
+                const label = item.active && on()
+                return <li key={item.name}>{label ? <span>yes</span> : <span>no</span>}</li>
+              })}
+            </ul>
+          </div>
+        )
+      }
+    `))
+
+    // The row-local `label` (the preamble's OWN computed value) must
+    // drive the branch — never the outer module const's literal.
+    expect(tpl).toContain('label ? `<span>yes</span>`')
+    expect(tpl).not.toContain("('MODULE_CONST')")
+    expect(tpl).not.toContain('MODULE_CONST')
+  })
+})

package/src/__tests__/csr-substitute-enclosing-scope.test.ts

@@ -0,0 +1,77 @@
+/**
+ * #2482 Stage 1b — `csrSubstitute`'s `enclosingScope` parameter.
+ *
+ * `csrSubstitute`'s `boundStack` only ever learns about bindings found
+ * while walking the substituted expression's OWN AST (nested arrow/
+ * function parameters and block-scoped locals inside `value` itself) — it
+ * has no way to see a binding introduced OUTSIDE that expression, e.g. an
+ * enclosing `.map()` row's item/index/destructured/preamble binding.
+ * `enclosingScope` (a `BindingScope`) seeds those outer frames so
+ * `isBound` treats them identically to an in-expression arrow param.
+ *
+ * Direct unit coverage, not a full-pipeline conformance fixture: every
+ * current call site (`html-template.ts`'s `generateCsrTemplateWithOpts`)
+ * already pre-filters `env.substitutions` to remove loop-shadowed names
+ * BEFORE calling in (see the `loop` case's `childEnv` construction, itself
+ * migrated onto `BindingScope.enterLoopRow` in this same stage) — so by
+ * the time `csrSubstitute` runs inside a loop body today, the shadowed
+ * name is already absent from `env.substitutions` and `enclosingScope`
+ * never gets a chance to matter. This test exercises the module function
+ * directly, bypassing that pre-filtering, to pin the parameter's own
+ * contract in isolation: SHOULD a future call site ever hand `csrSubstitute`
+ * an unfiltered env alongside a loop's `BindingScope` (e.g. a caller that
+ * wants substitution and shadow-guarding as one step instead of two), the
+ * shadow guard already works correctly.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { csrSubstitute, type CsrEnv } from '../ir-to-client-js/csr-substitute.ts'
+import { BindingScope } from '../scope/binding-scope.ts'
+
+describe('csrSubstitute enclosingScope (#2482)', () => {
+  test('a name bound by the enclosing loop scope is left unsubstituted, even though the env still has an entry for it', () => {
+    // Deliberately UNFILTERED env — in real call sites this would already
+    // have `label` removed by the caller's own loop-scope filtering; here
+    // we keep it to isolate what `enclosingScope` alone contributes.
+    const env: CsrEnv = {
+      substitutions: new Map([
+        ['label', { kind: 'identifier', replacement: "'MODULE_CONST'", freeIdentifiers: new Set() }],
+      ]),
+      propsObjectName: null,
+    }
+    const scope = BindingScope.EMPTY.enterLoopRow({ param: 'label' })
+
+    const withoutScope = csrSubstitute('label', env)
+    const withScope = csrSubstitute('label', env, scope)
+
+    expect(withoutScope.rewritten).toBe("('MODULE_CONST')")
+    expect(withScope.rewritten).toBe('label')
+  })
+
+  test('a name NOT bound by the enclosing scope still substitutes normally', () => {
+    const env: CsrEnv = {
+      substitutions: new Map([
+        ['label', { kind: 'identifier', replacement: "'MODULE_CONST'", freeIdentifiers: new Set() }],
+      ]),
+      propsObjectName: null,
+    }
+    // Scope binds a DIFFERENT name (`item`) — `label` stays substitutable.
+    const scope = BindingScope.EMPTY.enterLoopRow({ param: 'item' })
+
+    const { rewritten } = csrSubstitute('label', env, scope)
+    expect(rewritten).toBe("('MODULE_CONST')")
+  })
+
+  test('a preamble-bound name (not item/index/destructure) is also guarded', () => {
+    const env: CsrEnv = {
+      substitutions: new Map([
+        ['label', { kind: 'identifier', replacement: "'MODULE_CONST'", freeIdentifiers: new Set() }],
+      ]),
+      propsObjectName: null,
+    }
+    const scope = BindingScope.EMPTY.enterLoopRow({ param: 'item', preamble: { declaredNames: ['label'] } })
+
+    const { rewritten } = csrSubstitute('label', env, scope)
+    expect(rewritten).toBe('label')
+  })
+})

package/src/__tests__/identifier-pattern.test.ts

@@ -0,0 +1,170 @@
+/**
+ * #2592 — `$`-containing identifiers broke the compiler's
+ * `new RegExp(`\\b${name}\\b`)` "does this expression reference identifier
+ * X?" heuristic in two ways: an unescaped `$` acts as a regex end anchor
+ * (false negative anywhere but the very end of the pattern), and even once
+ * escaped, `\b` treats `$` as a non-word character, so it fails to find a
+ * boundary between e.g. `(` and a leading `$` (both non-word — no
+ * transition). See `../identifier-pattern.ts` for the fix.
+ */
+import { describe, test, expect } from 'bun:test'
+import { identifierPattern, identifierCallPattern } from '../identifier-pattern.ts'
+import { compileJSX } from '../compiler.ts'
+import { TestAdapter } from '../adapters/test-adapter.ts'
+
+describe('identifierPattern (#2592)', () => {
+  describe.each(['$item', 'item$', 'a$b', 'item'])('name = %p', (name) => {
+    test('matches a standalone parenthesized reference', () => {
+      expect(identifierPattern(name).test(`(${name})`)).toBe(true)
+    })
+
+    test('matches a reference after a binary operator', () => {
+      expect(identifierPattern(name).test(`x + ${name}`)).toBe(true)
+    })
+
+    test('matches as the base of a member-access expression', () => {
+      expect(identifierPattern(name).test(`${name}.foo`)).toBe(true)
+    })
+
+    test('does not match when it is a substring of a longer identifier (suffix)', () => {
+      expect(identifierPattern(name).test(`my${name}`)).toBe(false)
+    })
+
+    test('does not match when it is a substring of a longer identifier (prefix)', () => {
+      expect(identifierPattern(name).test(`${name}s`)).toBe(false)
+    })
+
+    test('does not match when it appears as a substring inside another identifier', () => {
+      // e.g. name="item" inside "xitem" / name="$item" inside "x$item"
+      expect(identifierPattern(name).test(`x${name}`)).toBe(false)
+    })
+  })
+
+  // Literal spellings from the issue, so the fixture reads without having
+  // to mentally substitute the parameterised %p name above.
+  test('$item: matches ($item), x + $item, $item.foo', () => {
+    const re = identifierPattern('$item')
+    expect(re.test('($item)')).toBe(true)
+    expect(re.test('x + $item')).toBe(true)
+    expect(re.test('$item.foo')).toBe(true)
+  })
+
+  test('$item: does not match my$item, $items, item$s, aitem, xitem', () => {
+    const re = identifierPattern('$item')
+    expect(re.test('my$item')).toBe(false)
+    expect(re.test('$items')).toBe(false)
+    expect(re.test('item$s')).toBe(false)
+    expect(re.test('aitem')).toBe(false)
+    expect(re.test('xitem')).toBe(false)
+  })
+
+  test('item (plain, no $) still matches only standalone references', () => {
+    const re = identifierPattern('item')
+    expect(re.test('(item)')).toBe(true)
+    expect(re.test('x + item')).toBe(true)
+    expect(re.test('item.foo')).toBe(true)
+    expect(re.test('my$item')).toBe(false)
+    expect(re.test('$items')).toBe(false)
+    expect(re.test('item$s')).toBe(false)
+    expect(re.test('aitem')).toBe(false)
+    expect(re.test('xitem')).toBe(false)
+  })
+
+  test('the `g` flag supports substitution scanning across multiple matches', () => {
+    const re = identifierPattern('$x', 'g')
+    expect('$x + $x'.replace(re, () => 'Y')).toBe('Y + Y')
+  })
+
+  test('regex-metacharacter identifiers are escaped, not interpreted', () => {
+    // Not a realistic JS identifier, but guards the escape step directly:
+    // an unescaped '.' would match any character.
+    const re = identifierPattern('a.b')
+    expect(re.test('a.b')).toBe(true)
+    expect(re.test('axb')).toBe(false)
+  })
+})
+
+describe('identifierCallPattern (#2592)', () => {
+  test('matches call syntax for a $-prefixed getter, with or without whitespace', () => {
+    expect(identifierCallPattern('$count').test('$count()')).toBe(true)
+    expect(identifierCallPattern('$count').test('$count ()')).toBe(true)
+    expect(identifierCallPattern('$count').test('1 + $count()')).toBe(true)
+  })
+
+  test('does not match a bare (non-call) reference', () => {
+    expect(identifierCallPattern('$count').test('$count')).toBe(false)
+  })
+
+  test('does not match when the name is a substring of a longer call', () => {
+    expect(identifierCallPattern('$count').test('my$count()')).toBe(false)
+    expect(identifierCallPattern('$count').test('$counter()')).toBe(false)
+  })
+
+  test('plain (non-$) getter names keep matching call syntax as before', () => {
+    expect(identifierCallPattern('count').test('count()')).toBe(true)
+    expect(identifierCallPattern('count').test('acount()')).toBe(false)
+    expect(identifierCallPattern('count').test('counter()')).toBe(false)
+  })
+})
+
+// -----------------------------------------------------------------------------
+// End-to-end: a `.map()` callback whose param is `$item` must classify
+// identically to one named `item` — same slotId allocation, same
+// `$item() ` accessor-wrapping in the emitted client JS. Before the fix,
+// `referencesLoopParam` / `wrapLoopParamAsAccessor`'s `\b$item\b` pattern
+// never matched, so the loop body silently lost slotId/reactive
+// classification for the `$item`-named param (wrong-but-silent: `bun test`
+// still passed because nothing asserted the accessor wrap for a `$`-param
+// until now). Verified red-without/green-with: reverting `identifier-
+// pattern.ts` to a plain `` new RegExp(`\\b${name}\\b`) ``-style
+// implementation fails this describe block while leaving the plain-`item`
+// sibling test green — see PR description for the local repro.
+// -----------------------------------------------------------------------------
+describe('$-prefixed loop param compiles identically to a plain-named one (#2592)', () => {
+  const adapter = new TestAdapter()
+
+  function compileMapBody(param: string): string {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      type Row = { id: number; label: string }
+      export function List() {
+        const [rows] = createSignal<Row[]>([])
+        return (
+          <ul>
+            {rows().map((${param}) => (
+              <Card key={${param}.id}>
+                <CardHeader>{${param}.label}</CardHeader>
+              </Card>
+            ))}
+          </ul>
+        )
+      }
+    `
+    const result = compileJSX(source, 'List.tsx', { adapter })
+    const errors = result.errors.filter(e => e.severity === 'error')
+    if (errors.length > 0) throw new Error(errors.map(e => e.message).join('\n'))
+    return result.files.find(f => f.type === 'clientJs')!.content
+  }
+
+  test('a plain `item` param is wrapped as an accessor in the child component prop', () => {
+    const js = compileMapBody('item')
+    expect(js).toContain('item().label')
+  })
+
+  test('a `$item` param is wrapped as an accessor identically (was previously left bare)', () => {
+    const js = compileMapBody('$item')
+    expect(js).toContain('$item().label')
+    expect(js).toContain('$item().id')
+  })
+})
+
+describe('flags handling', () => {
+  test("passing flags that already include 'u' does not throw (no duplicate flag)", () => {
+    const p = identifierPattern('item', 'gu')
+    expect(p.flags).toBe('gu')
+    const c = identifierCallPattern('item', 'u')
+    expect(c.flags).toBe('u')
+    expect('a item b item'.replace(identifierPattern('item', 'gu'), 'x')).toBe('a x b x')
+  })
+})

package/src/__tests__/let-type-annotation.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Regression test for #2589: a `let` declaration's explicit type
+ * annotation was dropped in emitted `.tsx` SSR templates —
+ * `let x: HTMLTextAreaElement | null = null` emitted as `let x = null`,
+ * which TypeScript then infers as `null`/`never`, producing
+ * TS7034/TS7005 (and TS2339 via `never` narrowing) under strict mode.
+ * Runtime output (client JS) was always correct — this is a type-level
+ * emission defect in the SSR template only.
+ *
+ * `ConstantInfo.typeAnnotation` (verbatim `node.type.getText()`, only
+ * present when the author wrote an explicit annotation) is now threaded
+ * through and printed by the `HonoAdapter` (`JsxAdapter` base) for `let`
+ * declarations, both function-scope and module-scope, initialized and
+ * uninitialized. `const` declarations are deliberately left unchanged:
+ * their type always infers correctly from the (immutable) initializer,
+ * so emitting an annotation there would only churn output for no
+ * typecheck gain (see the design note in the class docstring / #2589).
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { HonoAdapter } from '../../../../packages/adapter-hono/src/adapter/hono-adapter'
+
+describe('let type annotation preservation in emitted templates (#2589)', () => {
+  test('function-scope initialized let keeps its explicit type annotation', () => {
+    const honoAdapter = new HonoAdapter()
+    // `status()` is called directly from the returned JSX (unlike an
+    // `onXxx` event-handler prop, which the SSR template stubs to a
+    // no-op), so its body — and transitively `textareaEl`, which the
+    // effect-guard shape (`syncScroll`, mirroring the issue) also reads —
+    // stays reachable and survives into the emitted template.
+    const source = `
+      'use client'
+      import { createSignal, createEffect } from '@barefootjs/client'
+
+      export function Textarea() {
+        let textareaEl: HTMLTextAreaElement | null = null
+        const [value, setValue] = createSignal('')
+
+        const syncScroll = () => {
+          if (textareaEl) {
+            textareaEl.scrollTop = textareaEl.scrollHeight
+          }
+        }
+
+        const status = () => (textareaEl ? 'ready' : 'idle')
+
+        createEffect(() => {
+          value()
+          syncScroll()
+        })
+
+        return <div>{status()}</div>
+      }
+    `
+
+    const result = compileJSX(source, 'Textarea.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    expect(template.content).toContain('let textareaEl: HTMLTextAreaElement | null = null')
+  })
+
+  test('module-scope initialized let keeps its explicit type annotation', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      let exportModulePromise: Promise<{ x: number }> | null = null
+
+      export function Loader() {
+        const [status, setStatus] = createSignal('idle')
+
+        const load = () => {
+          exportModulePromise = Promise.resolve({ x: 1 })
+          setStatus('loaded')
+        }
+
+        return <button onClick={load}>{status()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'Loader.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    expect(template.content).toContain(
+      'let exportModulePromise: Promise<{ x: number }> | null = null',
+    )
+  })
+
+  test('module-scope uninitialized let keeps its explicit type annotation', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      let pending: number
+
+      export function Counter() {
+        const [count, setCount] = createSignal(0)
+
+        const bump = () => {
+          pending = count() + 1
+          setCount(pending)
+        }
+
+        return <button onClick={bump}>{count()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'Counter.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    expect(template.content).toContain('let pending: number')
+  })
+
+  test('unannotated let does NOT gain an inferred type annotation', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function Toggle() {
+        let y = null
+        const [open, setOpen] = createSignal(false)
+
+        const flip = () => {
+          y = open() ? 1 : null
+          setOpen(!open())
+        }
+
+        return <button onClick={flip}>{open() ? 'on' : 'off'}{String(y)}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'Toggle.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    // No annotation must be synthesized from inference — only an
+    // explicit source annotation is ever printed (`typeAnnotation`,
+    // never `type` for an initialized declaration).
+    expect(template.content).toContain('let y = null')
+    expect(template.content).not.toMatch(/let y\s*:/)
+  })
+
+  test('const with an explicit annotation is unchanged (no annotation added at emit)', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function Labelled() {
+        const label: string = 'hello'
+        const [count, setCount] = createSignal(0)
+        return <button onClick={() => setCount(count() + 1)}>{label}{count()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'Labelled.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    // By design (#2589 scoping decision) only `let` gets its annotation
+    // re-emitted — `const` infers correctly from its initializer already,
+    // so this stays `const label = 'hello'` with no annotation added.
+    expect(template.content).toContain("const label = 'hello'")
+    expect(template.content).not.toContain('const label: string')
+  })
+
+  test('ambient `declare let` is not re-emitted as a runtime binding', () => {
+    const honoAdapter = new HonoAdapter()
+    // `declare let` is a type-only contract: it has no initializer and
+    // carries NodeFlags.Let, so after the uninitialized-`let` collection
+    // fix it would match the module-scope collector unless ambient
+    // statements are excluded. Re-emitting it as a runtime `let` would
+    // shadow the real global with `undefined` in the SSR module.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      declare let __BF_AMBIENT__: string
+
+      export function Widget() {
+        const [n, setN] = createSignal(0)
+        const status = () => (__BF_AMBIENT__ ? 'set' : 'unset')
+        return <button onClick={() => setN(n() + 1)}>{status()}{n()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'Widget.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    // The reference inside `status` may survive, but no runtime `let`
+    // declaration for the ambient name may be emitted.
+    expect(template.content).not.toMatch(/^\s*let __BF_AMBIENT__/m)
+  })
+})

package/src/__tests__/loop-child-reactive-attr-const-shadow.test.ts

@@ -0,0 +1,107 @@
+/**
+ * #2482 Stage 1b — `prop-handling.ts`'s `expandConstantForReactivity` /
+ * `expandDynamicPropValue` run on `ClientJsContext`, a per-component object
+ * with no loop-scope field at all. Both do a flat
+ * `ctx.localConstants.find((c) => c.name === trimmedValue)` lookup with no
+ * awareness that the expression being expanded might be sitting inside a
+ * `.map()` row whose OWN item/index/destructured/preamble binding shadows
+ * that same-named module/component-level const — the lookup resolves to
+ * the OUTER const's value regardless.
+ *
+ * This test pins the reachable, currently-shipping instance: a per-item
+ * reactive DOM attribute (forced via `/* @client *\/`, so it bypasses the
+ * loop-param-only reactivity classifier and always reaches
+ * `collectLoopChildReactiveAttrs` → `expandConstantForReactivity`) whose
+ * value is a bare reference to the loop's OWN item parameter, which
+ * shares a name with a module-level const. Before the fix, the per-item
+ * `createEffect`-equivalent (`applyItem`/`createRow` in the lazy-row
+ * runtime) baked in the outer const's fixed literal for every row instead
+ * of reading the row's own item value — every row rendered the SAME
+ * `data-label`, and it never diverged from that one baked value.
+ *
+ * Modeled on `csr-template-loop-shadowing.test.ts` (the sibling shadowing
+ * fix for the CSR *template* lambda, #2222) — this is the analogous fix
+ * for the per-item *reactive attribute effect* body, a different codegen
+ * path (`reactivity.ts`'s `collectLoopChildReactiveAttrs`, not
+ * `html-template.ts`).
+ *
+ * A second describe block below pins the INDEX-param shadowing case
+ * (Copilot review on PR #2595): `buildLoopRowScope` initially omitted
+ * the loop's second callback param (`.map((item, i) => ...)`'s `i`) from
+ * the `BindingScope` it builds, so an `i`-shadows-a-module-const attr
+ * const-folded the outer value exactly like the item-param case above,
+ * empirically confirmed reachable through the same
+ * `collectLoopChildReactiveAttrs` → `expandConstantForReactivity` path.
+ * Fixed by threading the IR loop's `index` field through
+ * `collectLoopChildBindings` / `collectLoopChildConditionals` /
+ * `summarizeLoopChildBranch` / `collectLoopChildReactiveAttrs` /
+ * `collectLoopChildReactiveTexts` into `buildLoopRowScope`.
+ */
+
+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
+}
+
+describe('loop-child reactive attr vs a loop-param shadowing a module const (#2482)', () => {
+  test('a /* @client */ attr reading the shadowing item param reads the row value, not the outer const', () => {
+    const js = clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget({ items }: { items: string[] }) {
+        const label = 'MODULE_CONST'
+        const [n, setN] = createSignal(0)
+        return (
+          <div onClick={() => setN(n() + 1)}>
+            <ul>
+              {items.map((label) => (
+                <li key={label} data-label={/* @client */ label}>{n()}</li>
+              ))}
+            </ul>
+          </div>
+        )
+      }
+    `)
+
+    // The per-item attribute effect must read the row's OWN item
+    // accessor — never the outer module const's baked literal.
+    expect(js).toContain('const __x = label()')
+    expect(js).not.toContain("const __x = 'MODULE_CONST'")
+  })
+})
+
+describe('loop-child reactive attr vs a loop INDEX param shadowing a module const (#2482 / #2595)', () => {
+  test('a /* @client */ attr reading the shadowing index param reads the row index, not the outer const', () => {
+    const js = clientJsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Widget({ items }: { items: string[] }) {
+        const i = 'MODULE_CONST'
+        const [n, setN] = createSignal(0)
+        return (
+          <div onClick={() => setN(n() + 1)}>
+            <ul>
+              {items.map((item, i) => (
+                <li key={item} data-idx={/* @client */ i}>{n()}</li>
+              ))}
+            </ul>
+          </div>
+        )
+      }
+    `)
+
+    // The per-item attribute effect must read the row's OWN index
+    // closure variable — never the outer module const's baked literal.
+    expect(js).toContain("const __v = i;")
+    expect(js).not.toContain("const __v = 'MODULE_CONST';")
+  })
+})