@barefootjs/jsx 0.26.2 → 0.26.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/jsx",
-  "version": "0.26.2",
+  "version": "0.26.3",
   "description": "JSX compiler for BarefootJS - transforms JSX to server HTML + client JS",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,7 +53,7 @@
     "directory": "packages/jsx"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.26.2"
+    "@barefootjs/shared": "0.26.3"
   },
   "peerDependencies": {
     "@barefootjs/client": ">=0.2.0",

package/src/__tests__/__snapshots__/doc-examples.test.ts.snap

@@ -1203,6 +1203,71 @@ hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"><!--bf-
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L188 — ❌ BF021 on Go/Mojo — a JS-runtime target (Hono, CSR) runs the comparator 1`] = `
+"import { $, $t, __bfText, createComponent, createEffect, createSignal, escapeText, hydrate, initChild, mapArray, renderChild } from '@barefootjs/client/runtime'
+
+export function initTodoItem(__scope, _p = {}) {
+  if (!__scope) return
+  const __scopeId = __scope.getAttribute('bf-s')
+
+  const [_s0] = $t(__scope, 's0')
+
+  let __anchor_s0 = _s0
+  createEffect(() => {
+    const __val = String(_p.todo)
+    __anchor_s0 = __bfText(__anchor_s0, __val)
+  })
+
+}
+
+hydrate('TodoItem__b3c36eee', { init: initTodoItem, template: (_p) => \`<li bf="s1"><!--bf:s0-->\${escapeText(String(_p.todo))}<!--/--></li>\` })
+export function TodoItem(_p, __bfKey) { return createComponent('TodoItem__b3c36eee', _p, __bfKey) }
+export function initItem(__scope, _p = {}) {
+  if (!__scope) return
+  const __scopeId = __scope.getAttribute('bf-s')
+
+  const [_s0] = $t(__scope, 's0')
+
+  let __anchor_s0 = _s0
+  createEffect(() => {
+    const __val = String(_p.item)
+    __anchor_s0 = __bfText(__anchor_s0, __val)
+  })
+
+}
+
+hydrate('Item__b3c36eee', { init: initItem, template: (_p) => \`<li bf="s1"><!--bf:s0-->\${escapeText(String(_p.item))}<!--/--></li>\` })
+export function Item(_p, __bfKey) { return createComponent('Item__b3c36eee', _p, __bfKey) }
+function initDashboard() {}
+
+hydrate('Dashboard__b3c36eee', { init: initDashboard, template: (_p) => \`<div>D</div>\` })
+export function Dashboard(_p, __bfKey) { return createComponent('Dashboard__b3c36eee', _p, __bfKey) }
+export function initExample(__scope, _p = {}) {
+  if (!__scope) return
+  const __scopeId = __scope.getAttribute('bf-s')
+
+  const children = _p.children
+  const [count, setCount] = createSignal(0)
+  const [isLoggedIn] = createSignal(false)
+  const [todos] = createSignal([])
+  const [items] = createSignal([])
+  const [filter] = createSignal('all')
+  const [accepted] = createSignal(false)
+  const [text, setText] = createSignal('')
+
+  const [_s1] = $(__scope, 's1')
+
+  mapArray(() => items().sort((a, b) => { let r = 0; r = a.name > b.name ? 1 : -1; return r }), _s1, (item) => String(item.id), (item, __idx, __existing) => {
+    if (__existing) { initChild('Item__b3c36eee', __existing, { get item() { return item() } }); return __existing }
+    return createComponent('Item__b3c36eee', { get item() { return item() } }, item().id)
+  }, 'l0')
+
+}
+
+hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"><!--bf-loop:l0-->\${([]).sort((a, b) => { let r = 0; r = a.name > b.name ? 1 : -1; return r }).map((item) => \`\${renderChild('Item__b3c36eee', {item: item}, item.id)}\`).join('')}<!--bf-/loop:l0--></div>\` })
+export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
+`;
+
 exports[`docs/core/rendering/jsx-compatibility.md doc-examples L193 — ✅ Use /* @client */ 1`] = `
 "import { $, $t, __bfText, createComponent, createEffect, createSignal, escapeText, hydrate, initChild, mapArray, renderChild } from '@barefootjs/client/runtime'
 
@@ -1268,6 +1333,35 @@ hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"><!--bf-
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L205 — ❌ BF021 on Go/Mojo — \`byPrice\` is imported, not declared in this file 1`] = `
+"import { $, $t, createComponent, createEffect, escapeText, hydrate, mapArray, tAfter } from '@barefootjs/client/runtime'
+import { byPrice } from './comparators'
+
+
+export function initSortedList(__scope, _p = {}) {
+  if (!__scope) return
+  const __scopeId = __scope.getAttribute('bf-s')
+
+  const items = _p.items
+
+  const [_s1] = $(__scope, 's1')
+
+  const __tpl_l0 = document.createElement('template')
+  __tpl_l0.innerHTML = \`<li data-key=""><!--bf:s0--><!--/--></li>\`
+  mapArray(() => items.sort(byPrice), _s1, (item) => String(item.id), (item, __idx, __existing) => {
+    const __el = __existing ?? __tpl_l0.content.firstElementChild.cloneNode(true)
+    const __p = __existing ? null : [__el.firstChild]
+    { const __rt_s0 = __p ? tAfter(__p[0]) : $t(__el, 's0')[0]
+    if (__rt_s0) createEffect(() => { __rt_s0.textContent = String(item().name) }) }
+    return __el
+  }, 'l0')
+
+}
+
+hydrate('SortedList__b3c36eee', { init: initSortedList, template: (_p) => \`<ul bf="s1"><!--bf-loop:l0-->\${_p.items.sort(byPrice).map((item) => \`<li data-key="\${item.id}"><!--bf:s0-->\${escapeText(item.name)}<!--/--></li>\`).join('')}<!--bf-/loop:l0--></ul>\` })
+export function SortedList(_p, __bfKey) { return createComponent('SortedList__b3c36eee', _p, __bfKey) }"
+`;
+
 exports[`docs/core/rendering/jsx-compatibility.md doc-examples L211 — ✅ Use /* @client */, or inline / re-declare the comparator locally 1`] = `
 "import { $, $t, __bfText, createComponent, createEffect, createSignal, escapeText, hydrate, initChild, mapArray, renderChild } from '@barefootjs/client/runtime'
 

package/src/__tests__/client-js-generation.test.ts

@@ -1824,11 +1824,11 @@ describe('Client JS generation', () => {
         }
         const loop = findLoop(ir.root)
         expect(loop).toBeTruthy()
-        expect(loop.mapPreamble).toBeUndefined()
+        expect(loop.preamble).toBeUndefined()
       }
     })
 
-    test('generates mapPreamble in IR', () => {
+    test('generates the structured preamble in IR', () => {
       const source = `
         'use client'
         import { createSignal } from '@barefootjs/client'
@@ -1866,7 +1866,14 @@ describe('Client JS generation', () => {
       }
       const loop = findLoop(ir.root)
       expect(loop).toBeTruthy()
-      expect(loop.mapPreamble).toContain('const label = item.name.toUpperCase()')
+      // Structured carrier (Stage 3 root cure): the declaration lands in the
+      // preamble's js segments; the IR stays plain serializable data.
+      const jsText = loop.preamble.segments
+        .filter((s: any) => s.kind === 'js')
+        .map((s: any) => s.text)
+        .join('')
+      expect(jsText).toContain('const label = item.name.toUpperCase()')
+      expect(loop.preamble.declaredNames).toContain('label')
       expect(loop.children).toHaveLength(1)
       expect(loop.children[0].type).toBe('element')
     })

package/src/__tests__/compiler-stress-1244.test.ts

@@ -1115,7 +1115,18 @@ describe('<Async> body error path — sync throw + async reject (#1375)', () =>
 })
 
 describe('createPortal inside .map() — per-item portal owner tracking', () => {
-  test('one portal created per loop item', () => {
+  // SURFACED LIMITATION. Passing *inline* JSX as a `createPortal` argument is
+  // an unsupported shape: there is no compiler lowering for it (the JSX is
+  // never compiled to DOM ops) and no runtime per-loop-item portal tracking.
+  // Here the `createPortal(<div>…</div>, …)` sits as a non-return statement in
+  // a `.map()` callback, so as of Stage 3 of spec/callback-fidelity.md the
+  // generic "map body builds JSX in a preamble statement" guard refuses it
+  // with BF021 — replacing what was previously a *silent* leak of the raw
+  // `<div>{it.body}</div>` verbatim into the client bundle. The body below
+  // asserts the intended end state (compiles clean, one portal per item);
+  // drop `.todo` once inline-JSX createPortal (and per-item owner tracking)
+  // is actually implemented.
+  test.todo('one portal created per loop item', () => {
     const src = `
       'use client'
       import { createSignal, createPortal } from '@barefootjs/client'

package/src/__tests__/event-delegation-scope-2367.test.ts

@@ -0,0 +1,108 @@
+/**
+ * BarefootJS Compiler - Delegated handler slot lookups are scoped (#2367)
+ *
+ * A stateful component's delegated event handlers resolve the child slot that
+ * owns an event with `target.closest('[bf="sN"]')`. Because `bf` ids are
+ * assigned **per component**, the same id string legitimately exists in
+ * several components — so an *unscoped* `closest()` climbs across component
+ * boundaries and can match a same-id element in an ancestor component. The
+ * delegation then takes the wrong branch, fails a downstream lookup, and
+ * silently drops the real handler (no error thrown).
+ *
+ * The fix guards the match with `<container>.contains(sNEl)`. The delegating
+ * container holds every slot it delegates on, so a same-id element in an
+ * *ancestor* component (never a descendant of the container) is rejected and
+ * the handler falls through to the correct branch — without growing the
+ * client runtime (native `closest` + native `contains`).
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+describe('delegated handler slot lookups are container-scoped (#2367)', () => {
+  test('keyed dynamic loop guards each slot match with container.contains', () => {
+    // WordTable-shaped repro: a <tbody> delegates keydown to two input slots
+    // (front/back). Each slot match must be gated to the tbody container.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      interface Row { id: string; front: string; back: string }
+
+      export function WordTable() {
+        const [rows, setRows] = createSignal<Row[]>([])
+        const handleFront = (row: Row) => console.log('front', row.id)
+        const handleBack = (row: Row) => console.log('back', row.id)
+
+        return (
+          <table>
+            <tbody>
+              {rows().map(row => (
+                <tr key={row.id}>
+                  <td><input onKeyDown={() => handleFront(row)} /></td>
+                  <td><input onKeyDown={() => handleBack(row)} /></td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )
+      }
+    `
+    const result = compileJSX(source, 'WordTable.tsx', { adapter })
+    expect(result.errors).toHaveLength(0)
+
+    const clientJs = result.files.find(f => f.type === 'clientJs')!
+    const content = clientJs.content
+
+    // Delegation is wired on the tbody container.
+    expect(content).toContain(".addEventListener('keydown', (__bfEvt) => {")
+
+    // The container variable the listener is attached to.
+    const containerMatch = content.match(/if \((_s\d+)\) \1\.addEventListener\('keydown'/)
+    expect(containerMatch).not.toBeNull()
+    const container = containerMatch![1]
+
+    // Both slot branches gate the match on `<container>.contains(sNEl)` so a
+    // same-id element in an ancestor component (never a descendant of the
+    // container) can't be taken.
+    const guards = [...content.matchAll(/if \((s\d+)El && (_s\d+)\.contains\(\1El\)\)/g)]
+    expect(guards.length).toBe(2)
+    for (const m of guards) {
+      expect(m[2]).toBe(container)
+    }
+
+    // The lookup itself stays a plain native `closest` — no new runtime helper.
+    expect(content).toContain(`target.closest('[bf="`)
+    expect(content).not.toContain('closestWithin')
+  })
+
+  test('static-array delegation is also gated by container.contains', () => {
+    const source = `
+      'use client'
+
+      export function List() {
+        const items = [{ id: '1', label: 'A' }, { id: '2', label: 'B' }]
+        const handleClick = (id: string) => console.log('item', id)
+
+        return (
+          <ul>
+            {items.map(item => (
+              <li key={item.id}>
+                <button onClick={() => handleClick(item.id)}>Go</button>
+              </li>
+            ))}
+          </ul>
+        )
+      }
+    `
+    const result = compileJSX(source, 'List.tsx', { adapter })
+    expect(result.errors).toHaveLength(0)
+
+    const content = result.files.find(f => f.type === 'clientJs')!.content
+    expect(content).toMatch(/if \(s\d+El && _s\d+\.contains\(s\d+El\)\)/)
+    expect(content).not.toContain('closestWithin')
+  })
+})

package/src/__tests__/flatmap-segments.test.ts

@@ -0,0 +1,80 @@
+/**
+ * flatMap block bodies ride the structured-segments carrier (flatMap
+ * unification, spec/callback-fidelity.md root cure): the same
+ * `renderPreamble()` door as `.map()` preambles, no `__BF_JSX_N__` sentinel.
+ * Pins the two behavior fixes that ride the shared machinery:
+ *
+ * - leaf text interpolations escape like the SSR JSX runtime (`escapeText`),
+ * - TS type annotations in the block body are stripped from the client
+ *   bundle (the old raw-slice carrier spliced them verbatim — invalid JS).
+ *
+ * Byte-level SSR/CSR parity for flatMap block bodies is NOT pinned at the
+ * conformance layer: the CSR string render and the Hono rawBody SSR have
+ * pre-existing structural asymmetries (leaf `data-key` emitted client-side
+ * only, with an unescaped attribute value; slot comment markers client-side
+ * only) that predate the unification and need their own investigation —
+ * see the known-limitation issue referenced in the changeset.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+describe('flatMap block bodies on structured segments', () => {
+  test('leaf text interpolations are escapeText-wrapped in the client bundle', () => {
+    const src = `
+function F({ items }: { items: { id: string; tags: string[] }[] }) {
+  return <ul>{items.flatMap((it) => {
+    return it.tags.map((t) => <li key={t}>{t}</li>)
+  })}</ul>
+}
+export { F }
+`
+    const r = compileJSX(src, 'F.tsx', { adapter: new TestAdapter() })
+    expect(r.errors).toHaveLength(0)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    expect(cj).toMatch(/escapeText\(\(t\)\)/)
+    expect(cj).not.toMatch(/__BF_JSX_/)
+  })
+
+  test('destructured prop refs rewrite to _p.xxx in the hydrate template', () => {
+    // The hydrate registration template is module scope (`template: (_p) =>`),
+    // so a bare destructured-prop reference in the flatMap body would be a
+    // runtime ReferenceError. Per-segment templateText (rewriteBarePropRefs)
+    // + textVariant 'template' at the CSR-template site rewrite it.
+    const src = `
+function F({ limit, items }: { limit: number; items: { id: string; tags: string[] }[] }) {
+  return <ul>{items.flatMap((it) => {
+    if (it.tags.length > limit) return []
+    return it.tags.map((t) => <li key={t}>{t}</li>)
+  })}</ul>
+}
+export { F }
+`
+    const r = compileJSX(src, 'F.tsx', { adapter: new TestAdapter() })
+    expect(r.errors).toHaveLength(0)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    const tpl = cj.match(/template: \(_p\) => `[\s\S]*?` \}\)/)?.[0] ?? ''
+    expect(tpl).toMatch(/_p\.limit/)
+    expect(tpl).not.toMatch(/[^.\w]limit\b/)
+  })
+
+  test('TS type annotations in the block body are stripped from the client bundle', () => {
+    const src = `
+function F({ items }: { items: { id: string; labels: string[] }[] }) {
+  return <ul>{items.flatMap((it) => {
+    const upper: string[] = it.labels
+    return upper.map((l) => <li key={l}>{l}</li>)
+  })}</ul>
+}
+export { F }
+`
+    const r = compileJSX(src, 'F.tsx', { adapter: new TestAdapter() })
+    expect(r.errors).toHaveLength(0)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    // The annotation must not survive into plain JS...
+    expect(cj).not.toMatch(/upper: string\[\]/)
+    // ...while the declaration itself does.
+    expect(cj).toMatch(/const upper = it\.labels/)
+  })
+})

package/src/__tests__/map-arbitrary-body.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Stage 3 (D4 + D5) of spec/callback-fidelity.md — a `.map()` callback whose
+ * body *constructs* JSX in a statement before its `return` (an imperative
+ * array-builder: `const out = []; for (…) out.push(<td/>); return <tr>{out}</tr>`).
+ *
+ * On a **JS-runtime** adapter (`acceptsCallbackBody() => true`) the body is now
+ * rendered verbatim: each JSX leaf lowers to a template-literal HTML string, the
+ * imperative control flow runs as-is, and the `{out}` element-array child is
+ * joined into the row's innerHTML. No raw JSX leaks into the plain-JS bundle.
+ *
+ * On a **DSL** adapter (whose template runtime can't run a callback body) it
+ * still refuses with BF021, always naming the `/* @client *\/` escape.
+ *
+ * D5 (keyFn = hoist): the loop key is evaluated before the body runs, so it must
+ * be derivable from the raw item — a key that reads a preamble-computed local is
+ * refused (it would compile to an unbound keyFn).
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+function compile(source: string, dsl: boolean) {
+  const a = new TestAdapter()
+  // A DSL adapter's template runtime can't run a callback body verbatim.
+  if (dsl) a.acceptsCallbackBody = () => false
+  return compileJSX(source, 'List.tsx', { adapter: a })
+}
+
+const arrayBuilder = `
+function Table({ rows }: { rows: { id: string; cells: string[] }[] }) {
+  return <table><tbody>{rows.map((r) => {
+    const out = []
+    for (const c of r.cells) out.push(<td>{c}</td>)
+    return <tr key={r.id}>{out}</tr>
+  })}</tbody></table>
+}
+export { Table }
+`
+
+describe('.map() array-builder body — JS-runtime verbatim (Stage 3 / D4)', () => {
+  test('compiles with no BF021 on a JS-runtime adapter', () => {
+    const r = compile(arrayBuilder, false)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(0)
+  })
+
+  test('no raw JSX leaks into the client bundle; the leaf is a lowered string', () => {
+    const r = compile(arrayBuilder, false)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    // The raw `out.push(<td>…)` must not survive — raw JSX is invalid plain JS.
+    expect(cj).not.toMatch(/out\.push\(</)
+    // …it lowers to a template-literal HTML string instead.
+    expect(cj).toMatch(/out\.push\(`<td>/)
+  })
+
+  test('leaf text interpolations escape like the SSR JSX runtime (parity)', () => {
+    // A JSX-runtime SSR adapter auto-escapes `{c}`; the client's HTML-string
+    // lowering must escape the same position (renderPreamble's leaf door) or
+    // special characters in data would parse as markup client-side only.
+    // Byte-level parity is pinned by the map-array-builder-escaping fixture.
+    const r = compile(arrayBuilder, false)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    expect(cj).toMatch(/out\.push\(`<td>\$\{escapeText\(\(c\)\)\}<\/td>`\)/)
+  })
+
+  test('the element-array child {out} is joined into the row', () => {
+    const r = compile(arrayBuilder, false)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    // `out` is an array of HTML strings; the child interpolation must join it,
+    // not `String([])`-comma-collapse it.
+    expect(cj).toMatch(/Array\.isArray\(out\)\s*\?\s*out\.join\(''\)/)
+  })
+
+  test('keyFn is hoisted from the returned root and derived from the raw item', () => {
+    const r = compile(arrayBuilder, false)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    expect(cj).toMatch(/\(r\)\s*=>\s*String\(r\.id\)/)
+  })
+
+  test('DSL adapter refuses with BF021 naming the /* @client */ escape', () => {
+    const r = compile(arrayBuilder, true)
+    const bf021 = r.errors.filter(e => e.code === 'BF021')
+    expect(bf021).toHaveLength(1)
+    expect(bf021[0].suggestion?.message ?? '').toMatch(/@client/)
+  })
+
+  test('a /* @client */-marked array-builder compiles clean on a DSL adapter', () => {
+    // The escape: the loop renders client-only (the DSL SSR adapter emits
+    // markers, the browser runs the verbatim body), so the DSL refusal lifts.
+    const src = `
+function Table({ rows }: { rows: { id: string; cells: string[] }[] }) {
+  return <table><tbody>{/* @client */ rows.map((r) => {
+    const out = []
+    for (const c of r.cells) out.push(<td>{c}</td>)
+    return <tr key={r.id}>{out}</tr>
+  })}</tbody></table>
+}
+export { Table }
+`
+    const r = compile(src, true)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(0)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    // The browser still runs the verbatim body — the leaf is a lowered string.
+    expect(cj).toMatch(/out\.push\(`<td>/)
+  })
+})
+
+describe('.map() array-builder — {out} join is scoped to the bare identifier', () => {
+  test('only the bare {out} child joins; a property access on it does not', () => {
+    // `{out}` is the element-array child and must join; `{out.length}` is a
+    // number and must NOT get the array-join coercion (which would also
+    // double-read the expression).
+    const src = `
+function T({ rows }: { rows: { id: string; cells: string[] }[] }) {
+  return <table><tbody>{rows.map((r) => {
+    const out = []
+    for (const c of r.cells) out.push(<td>{c}</td>)
+    return <tr key={r.id}>{out}<td>{out.length}</td></tr>
+  })}</tbody></table>
+}
+export { T }
+`
+    const r = compile(src, false)
+    const cj = r.files.find(f => f.type === 'clientJs')!.content
+    expect(cj).toMatch(/Array\.isArray\(out\)\s*\?\s*out\.join\(''\)/)
+    expect(cj).not.toMatch(/Array\.isArray\(out\.length\)/)
+  })
+})
+
+describe('.map() array-builder — D5 keyFn hoist contract', () => {
+  test('a key derived from a preamble-computed local is refused', () => {
+    // `k` is computed in the body; the key runs *before* the body, so it cannot
+    // reference `k`. Refuse rather than emit an unbound keyFn.
+    const src = `
+function T({ rows }: { rows: { id: string; cells: string[] }[] }) {
+  return <table><tbody>{rows.map((r) => {
+    const k = r.id + '-row'
+    const out = []
+    for (const c of r.cells) out.push(<td>{c}</td>)
+    return <tr key={k}>{out}</tr>
+  })}</tbody></table>
+}
+export { T }
+`
+    const r = compile(src, false)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(1)
+  })
+
+  test('a key derived from a destructured preamble local is refused', () => {
+    // The guard must see `k` even when it is bound via destructuring — else it
+    // would compile to a keyFn referencing an unbound `k`.
+    const src = `
+function T({ rows }: { rows: { meta: { id: string }; cells: string[] }[] }) {
+  return <table><tbody>{rows.map((r) => {
+    const { id: k } = r.meta
+    const out = []
+    for (const c of r.cells) out.push(<td>{c}</td>)
+    return <tr key={k}>{out}</tr>
+  })}</tbody></table>
+}
+export { T }
+`
+    const r = compile(src, false)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(1)
+  })
+})
+
+describe('.map() array-builder — leaf scope (D-E: refuse what cannot be wired)', () => {
+  test('a leaf with an event handler is refused (no silent divergence)', () => {
+    const src = `
+function T({ rows }: { rows: { id: string; cells: string[] }[] }) {
+  return <table><tbody>{rows.map((r) => {
+    const out = []
+    for (const c of r.cells) out.push(<td onClick={() => console.log(c)}>{c}</td>)
+    return <tr key={r.id}>{out}</tr>
+  })}</tbody></table>
+}
+export { T }
+`
+    const r = compile(src, false)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(1)
+  })
+})
+
+describe('.map() arbitrary body — regression guards (unchanged)', () => {
+  test('a value-only const preamble still compiles clean (no false positive)', () => {
+    const src = `
+function List({ items }: { items: { id: string; name: string }[] }) {
+  return <ul>{items.map((it) => {
+    const label = it.name.toUpperCase()
+    return <li key={it.id}>{label}</li>
+  })}</ul>
+}
+export { List }
+`
+    const r = compile(src, false)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(0)
+    const cj = r.files.find(f => f.type === 'clientJs')!
+    expect(cj.content).toMatch(/const label\b/)
+  })
+
+  test('JSX in unreachable code after the return does not trip BF021', () => {
+    const src = `
+function List({ items }: { items: { id: string }[] }) {
+  return <ul>{items.map((it) => {
+    return <li key={it.id}>{it.id}</li>
+    const dead = <span>{it.id}</span>
+  })}</ul>
+}
+export { List }
+`
+    const r = compile(src, false)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(0)
+  })
+
+  test('a plain single-return JSX body is unaffected on a DSL adapter', () => {
+    const src = `
+function List({ items }: { items: { id: string }[] }) {
+  return <ul>{items.map((it) => { return <li key={it.id}>{it.id}</li> })}</ul>
+}
+export { List }
+`
+    const r = compile(src, true)
+    expect(r.errors.filter(e => e.code === 'BF021')).toHaveLength(0)
+  })
+})