@barefootjs/jsx 0.31.4 → 0.31.6

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

@@ -757,7 +757,7 @@ hydrate('Example', { init: initExample, template: (_p) => \`<div><button bf="s0"
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 
-exports[`docs/core/rendering/jsx-compatibility.md doc-examples L142 — ✅ Nested \`.filter()\` / \`.map()\` now compiles everywhere 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L143 — ✅ Nested \`.filter()\` / \`.map()\` now compiles everywhere 1`] = `
 "import { createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -815,7 +815,7 @@ 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 L149 — ❌ BF101 on Go/Mojo; works on Hono 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L150 — ❌ BF101 on Go/Mojo; works on Hono 1`] = `
 "import { createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -873,7 +873,7 @@ 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 L152 — ✅ Add /* @client */ to evaluate on the client 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L153 — ✅ Add /* @client */ to evaluate on the client 1`] = `
 "import { createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -927,11 +927,11 @@ export function initExample(__scope, _p = {}) {
 
 }
 
-hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"><!--bf:s0--><!--/--></div>\` })
+hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"></div>\` })
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 
-exports[`docs/core/rendering/jsx-compatibility.md doc-examples L159 — ❌ BF101 on Go/Mojo; works on Hono 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L160 — ❌ BF101 on Go/Mojo; works on Hono 1`] = `
 "import { createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -989,7 +989,7 @@ 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 L162 — ✅ Use /* @client */ 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L163 — ✅ Use /* @client */ 1`] = `
 "import { createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -1043,11 +1043,11 @@ export function initExample(__scope, _p = {}) {
 
 }
 
-hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"><!--bf:s0--><!--/--></div>\` })
+hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"></div>\` })
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 
-exports[`docs/core/rendering/jsx-compatibility.md doc-examples L179 — ❌ BF101 on Go/Mojo; works on Hono 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L180 — ❌ BF101 on Go/Mojo; works on Hono 1`] = `
 "import { createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -1105,7 +1105,7 @@ 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 L182 — ✅ Use arrow functions for adapter portability 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L183 — ✅ Use arrow functions for adapter portability 1`] = `
 "import { createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -1163,7 +1163,107 @@ 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 L195 — ✅ Value-producing block bodies normalize (let-inline) and lower everywhere 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L192 — ❌ BF101 on Go/Mojo/Xslate/Twig/ERB/Blade/Jinja/MiniJinja; works on Hono 1`] = `
+"import { $, createComponent, createEffect, escapeAttr, escapeText, hydrate, lazySlots } from '@barefootjs/client/runtime'
+
+
+export function initReactionBar(__scope, _p = {}) {
+  if (!__scope) return
+  const __scopeId = __scope.getAttribute('bf-s')
+
+  const entries = Object.entries(_p.reactions).filter(([, users]) => users.length > 0)
+
+  const [_s2] = $(__scope, 's2')
+
+  // Reactive texts / CSR materialize in static array children
+  if (_s2) {
+    entries.forEach(([emoji, users], __idx) => {
+      let __iterEl = _s2.children[__idx]
+      if (!__iterEl) {
+        const __tpl = document.createElement('template')
+        __tpl.innerHTML = \`<span data-key="\${escapeAttr(emoji)}"><!--bf:s0-->\${escapeText(emoji)}<!--/-->: <!--bf:s1-->\${escapeText(String(users.length))}<!--/--></span>\`
+        const __cloned = __tpl.content.firstElementChild
+        if (__cloned) {
+          const __anchor = _s2.children[__idx] ?? null
+          _s2.insertBefore(__cloned, __anchor)
+          __iterEl = __cloned
+        }
+      }
+      if (__iterEl) {
+        const __bfw_s0 = lazySlots(__iterEl, [{ id: 's0', kind: 'text', path: [] }, { id: 's1', kind: 'text', path: [] }])
+        createEffect(() => { __bfw_s0('s0', String(emoji)) })
+        createEffect(() => { __bfw_s0('s1', String(String(users.length))) })
+      }
+    })
+  }
+
+}
+
+hydrate('ReactionBar__b3c36eee', { init: initReactionBar, template: (_p) => \`<div bf="s2"><!--bf-loop:l0-->\${[].map(([emoji, users]) => \`<span data-key="\${escapeAttr(emoji)}"><!--bf:s0-->\${escapeText(emoji)}<!--/-->: <!--bf:s1-->\${escapeText(String(users.length))}<!--/--></span>\`).join('')}<!--bf-/loop:l0--></div>\`, name: 'ReactionBar' })
+export function ReactionBar(_p, __bfKey) { return createComponent('ReactionBar__b3c36eee', _p, __bfKey) }"
+`;
+
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L201 — ✅ Best: precompute the array in the parent/route handler and pass it as a prop 1`] = `
+"import { $, createComponent, escapeAttr, escapeText, hydrate, lazySlots, mapArrayLazy, textOrNode } from '@barefootjs/client/runtime'
+
+
+export function initReactionBarByProp(__scope, _p = {}) {
+  if (!__scope) return
+  const __scopeId = __scope.getAttribute('bf-s')
+
+  const entries = _p.entries ?? []
+
+  const [_s2] = $(__scope, 's2')
+
+  const __tpl_l0 = document.createElement('template')
+  __tpl_l0.innerHTML = \`<span data-key=""><!--bf:s0--><!--/-->: <!--bf:s1--><!--/--></span>\`
+  const __lzp_l0 = [[0], [3]]
+  const __lzs_l0 = [{ id: 's0', kind: 'text', path: [] }, { id: 's1', kind: 'text', path: [] }]
+  const __lzsc_l0 = [{ id: 's0', kind: 'text', path: __lzp_l0[0] }, { id: 's1', kind: 'text', path: __lzp_l0[1] }]
+  mapArrayLazy(() => entries, _s2, ([emoji, users]) => String(emoji), {
+    createRow: (__e, __idx) => {
+      const __bfItem = () => __e.item
+      const __el = __tpl_l0.content.firstElementChild.cloneNode(true)
+      const __r = __e.refs = [lazySlots(__el, __lzsc_l0)]
+      const __l = __e.last = []
+      { const __x = __bfItem()[0]
+      __r[0]('s0', textOrNode(__x))
+      __l[0] = __x }
+      { const __x = String(__bfItem()[1].length)
+      __r[0]('s1', textOrNode(__x))
+      __l[1] = __x }
+      return __el
+    },
+    applyItem: (__e) => {
+      const __bfItem = () => __e.item
+      const __r = __e.refs ?? (__e.refs = [])
+      const __l = __e.last ?? (__e.last = [])
+      const __d = __r[0] ?? (__r[0] = lazySlots(__e.primaryEl, __lzs_l0))
+      { const __x = __bfItem()[0]
+      if (!(0 in __l) || !Object.is(__l[0], __x)) __d('s0', textOrNode(__x))
+      __l[0] = __x }
+      { const __x = String(__bfItem()[1].length)
+      if (!(1 in __l) || !Object.is(__l[1], __x)) __d('s1', textOrNode(__x))
+      __l[1] = __x }
+    },
+  }, 'l0')
+
+}
+
+hydrate('ReactionBarByProp__b3c36eee', { init: initReactionBarByProp, template: (_p) => \`<div bf="s2"><!--bf-loop:l0-->\${_p.entries.map(([emoji, users]) => \`<span data-key="\${escapeAttr(emoji)}"><!--bf:s0-->\${escapeText(emoji)}<!--/-->: <!--bf:s1-->\${escapeText(String(users.length))}<!--/--></span>\`).join('')}<!--bf-/loop:l0--></div>\`, name: 'ReactionBarByProp' })
+export function ReactionBarByProp(_p, __bfKey) { return createComponent('ReactionBarByProp__b3c36eee', _p, __bfKey) }"
+`;
+
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L209 — ✅ Or defer to the client with /* @client */ 1`] = `
+"import { createComponent, hydrate } from '@barefootjs/client/runtime'
+
+function initStatementExample() {}
+
+hydrate('StatementExample', { init: initStatementExample, template: (_p) => \`<div></div>\` })
+export function StatementExample(_p, __bfKey) { return createComponent('StatementExample', _p, __bfKey) }"
+`;
+
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L229 — ✅ Value-producing block bodies normalize (let-inline) and lower everywhere 1`] = `
 "import { $, createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, initChild, lazySlots, mapArray, renderChild } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -1222,7 +1322,7 @@ 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 — a JS-runtime target (Hono, CSR) runs the comparator 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L239 — ❌ BF021 on Go/Mojo — a JS-runtime target (Hono, CSR) runs the comparator 1`] = `
 "import { $, createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, initChild, lazySlots, mapArray, renderChild } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -1281,7 +1381,7 @@ 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 L210 — ✅ Use /* @client */ 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L244 — ✅ Use /* @client */ 1`] = `
 "import { $, createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, initChild, lazySlots, mapArray, renderChild } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -1340,7 +1440,7 @@ 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 L222 — ❌ BF021 on Go/Mojo — \`byPrice\` is imported, not declared in this file 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L256 — ❌ BF021 on Go/Mojo — \`byPrice\` is imported, not declared in this file 1`] = `
 "import { $, createComponent, createEffect, escapeAttr, escapeText, hydrate, lazySlots, mapArray } from '@barefootjs/client/runtime'
 import { byPrice } from './comparators'
 
@@ -1368,7 +1468,7 @@ hydrate('SortedList__b3c36eee', { init: initSortedList, template: (_p) => \`<ul
 export function SortedList(_p, __bfKey) { return createComponent('SortedList__b3c36eee', _p, __bfKey) }"
 `;
 
-exports[`docs/core/rendering/jsx-compatibility.md doc-examples L228 — ✅ Use /* @client */, or inline / re-declare the comparator locally 1`] = `
+exports[`docs/core/rendering/jsx-compatibility.md doc-examples L262 — ✅ Use /* @client */, or inline / re-declare the comparator locally 1`] = `
 "import { $, createComponent, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, initChild, lazySlots, mapArray, renderChild } from '@barefootjs/client/runtime'
 
 export function initTodoItem(__scope, _p = {}) {
@@ -1481,7 +1581,7 @@ export function initExample(__scope, _p = {}) {
 
 }
 
-hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"><!--bf:s0--><!--/--></div>\` })
+hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"></div>\` })
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 
@@ -1539,7 +1639,7 @@ export function initExample(__scope, _p = {}) {
 
 }
 
-hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"><!--bf:s0--><!--/--></div>\` })
+hydrate('Example', { init: initExample, template: (_p) => \`<div bf="s1"></div>\` })
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 
@@ -1597,7 +1697,7 @@ export function initExample(__scope, _p = {}) {
 
 }
 
-hydrate('Example', { init: initExample, template: (_p) => \`<div><strong bf="s1"><!--bf:s0--><!--/--></strong></div>\` })
+hydrate('Example', { init: initExample, template: (_p) => \`<div><strong bf="s1"></strong></div>\` })
 export function Example(_p, __bfKey) { return createComponent('Example', _p, __bfKey) }"
 `;
 

package/src/__tests__/binding-scope-ratchet.test.ts

@@ -12,7 +12,9 @@
  * pattern covers both.
  * Modeled in spirit on `map-body-no-silent-divergence.test.ts`'s known-hole
  * ledger: a known-inventory of the current reality that may only shrink as
- * Stages 1-4 migrate call sites onto `BindingScope`, never grow.
+ * Stages 1-4 migrate call sites onto `BindingScope`, never grow. Stage 4
+ * drove this to its FLOOR — every remaining entry is a permanent, justified
+ * exception (see the `ALLOWLIST` doc comment below), not leftover debt.
  *
  * Scans every `.ts` file under `packages/jsx/src/` and each `packages/adapter-X/src/`
  * (excluding `__tests__` directories, `*.test.ts` files, and
@@ -58,44 +60,167 @@ const PATTERNS = [
 type Pattern = (typeof PATTERNS)[number]
 
 /**
- * Exact per-file, per-pattern occurrence counts as of #2482 Stage 0. Only
- * ever shrinks — see header comment. A missing file or missing pattern key
- * means an expected count of 0.
+ * Exact per-file, per-pattern occurrence counts, updated through #2482
+ * Stage 4 (the FLOOR — see that stage's PR for the file-by-file
+ * MIGRATE-or-FLOOR review). Only ever shrinks — see header comment. A
+ * missing file or missing pattern key means an expected count of 0.
+ *
+ * ============================== FLOOR INVARIANT ==============================
+ * Every entry below is a PERMANENT, JUSTIFIED exception, not leftover debt —
+ * each one is annotated with why it can't (or shouldn't) thread a live
+ * `BindingScope` instead. Two shapes recur across the justifications:
+ *
+ *   1. NO LIVE SCOPE TO CONSULT: a prepass that runs once at `generate()` /
+ *      constructor-generation time, OUTSIDE the render-time (or
+ *      render-shaped) tree walk `BindingScope` is threaded through — there is
+ *      no position to ask "what's bound HERE" about, so these fall back to a
+ *      coarser, deliberately over-inclusive whole-component or whole-file
+ *      scan (safe because over-exclusion only ever degrades to the
+ *      already-accepted pre-#2482 residual, never to silently wrong output).
+ *   2. UNRELATED DOMAIN: a `localConstants.find(` matching the ledger's
+ *      textual pattern by coincidence — const/prop resolution for SSR
+ *      dead-code elimination, `Record[key]` lookup, cross-IR CSS class
+ *      resolution, component-scope const-chain inlining — none of which ask
+ *      "is this name shadowed by a loop callback param" at all, so
+ *      `BindingScope` (a loop-row/callback binding stack) has no bearing on
+ *      them.
+ *   3. ACCESSOR/REWRITE PAYLOAD, NOT AN EXISTENCE QUERY: `BindingScope` only
+ *      carries binding EXISTENCE/kind/depth — never per-binding rendering
+ *      payload (a Go template accessor string, an ordered client-JS
+ *      accessor-rewrite spec). The Go adapter's `loopBindingStack` and the
+ *      client-JS emitter's `loopParams: ReadonlyArray<string | LoopParamSpec>`
+ *      (`ir-to-client-js/utils.ts`'s `wrapExprWithLoopParams` and its
+ *      `collect-elements.ts`/`html-template.ts`/`build-event-delegation.ts`
+ *      callers) are this shape — a `BindingScope`-adjacent but structurally
+ *      distinct concern.
+ *
+ * New code must use `BindingScope` (`packages/jsx/src/scope/binding-scope.ts`)
+ * for any "is this name bound by an enclosing loop callback" question. Per
+ * the mechanics already documented below: entries may only shrink (or be
+ * removed outright when a file reaches 0), never grow — a grown or added
+ * entry is a regression to flag in review, not to allowlist away.
+ * ===============================================================================
  */
 const ALLOWLIST: Record<string, Partial<Record<Pattern, number>>> = {
-  'packages/adapter-blade/src/adapter/blade-adapter.ts': { staticLoopSourceBoundNames: 8, loopBoundNames: 12 },
-  'packages/adapter-erb/src/adapter/erb-adapter.ts': { 'localConstants.find(': 1, loopBoundNames: 20 },
-  'packages/adapter-erb/src/adapter/expr/emitters.ts': { loopBoundNames: 1 },
+  // FLOOR (shape 1, already guarded): `expandDynamicPropValue`'s
+  // `this.scope`-mirroring shadow guard (`erb-adapter.ts`'s own
+  // `!this.scope.isBound(trimmed)` check, #2489) precedes this `.find(` —
+  // the lookup itself is the legitimate const-resolution step once the
+  // shadow question is already answered by `scope`.
+  'packages/adapter-erb/src/adapter/erb-adapter.ts': { 'localConstants.find(': 1 },
+  // FLOOR (shape 2/3 boundary): `inlineLocalHelperCall` resolves a call's
+  // CALLEE name against module/component consts to inline a local
+  // arrow-helper's body (`sortClass(k)` → its substituted expression) — a
+  // "does a helper by this name exist" lookup, not itself a shadow guard.
+  // Flagged for the human maintainer (see Stage 4 report): unlike the
+  // sibling `litConst` fast path directly above its call site in
+  // `go-template-adapter.ts` (which DOES guard with `isLoopShadowedName`),
+  // this call site has no such guard — a `.map((sortClass) => ...)`
+  // shadowing a same-named module helper is a narrow, unverified gap left
+  // for a follow-up rather than fixed speculatively here.
   'packages/adapter-go-template/src/adapter/expr/helper-inline.ts': { 'localConstants.find(': 1 },
   'packages/adapter-go-template/src/adapter/go-template-adapter.ts': {
+    // FLOOR: of the 5 `.find(` sites — `resolveDynamicPropValue` (child-prop
+    // passthrough, called only from `generateNewPropsFunction`'s
+    // `emitStaticChildInstances`), `computeDerivedConstFields` and
+    // `isStringExpr` (same `generateNewPropsFunction` constructor-context
+    // bucket), and `resolveModuleNumericConst` (guarded in place by
+    // `isCurrentLoopItem`/`isOuterLoopParam`, both already `this.scope.lookup`-
+    // backed) — 3 are shape-1 (no live scope in the ctor-generation prepass)
+    // and 1 is already scope-guarded. The 5th, `renderLoop`'s loop-array
+    // const lookup, gained a `!this.scope.isBound(arrayName)` guard in
+    // Stage 4 (a real gap: an enclosing loop's own item param could shadow
+    // a same-named module const and misfire a BF101) — MIGRATED in place,
+    // the `.find(` call itself stays as the legitimate lookup once shadow
+    // is ruled out.
     'localConstants.find(': 5,
-    staticLoopSourceBoundNames: 3,
-    loopParamStack: 35,
+    // #2482 Stage 3: `loopParamStack` eliminated entirely (0, down from 35)
+    // — replaced by the threaded `this.scope: BindingScope`. The remaining
+    // 2 `staticLoopSourceBoundNames` uses (down from 3) are the
+    // `getBakedStaticChildLoop` shadow guard shared with two call sites
+    // OUTSIDE the live `renderLoop` tree walk (no live `scope` to consult
+    // there — shape 1) — a genuinely-legitimate surviving use, confirmed
+    // FLOOR in Stage 4 (`primeCompileState`'s own comment documents the
+    // three-call-site agreement requirement).
+    staticLoopSourceBoundNames: 2,
   },
-  'packages/adapter-go-template/src/adapter/lib/compile-state.ts': { staticLoopSourceBoundNames: 1, loopParamStack: 1 },
+  // FLOOR (shape 1 for the field; the doc-only `loopParamStack` mention this
+  // file's top-level comment used to carry was reworded in Stage 4 — that
+  // stack no longer exists anywhere, so the ledger's last trace of it is
+  // gone too).
+  'packages/adapter-go-template/src/adapter/lib/compile-state.ts': { staticLoopSourceBoundNames: 1 },
+  // FLOOR (shape 1): `lowerCtorExpr`/`lowerCtorStringArray` lower a derived-
+  // state memo's computation into Go CODE evaluated in the `NewXxxProps`
+  // constructor — the same no-live-scope bucket as `go-template-adapter.ts`'s
+  // ctor-context `.find(` calls above.
   'packages/adapter-go-template/src/adapter/memo/ctor-lowering.ts': { 'localConstants.find(': 3 },
+  // FLOOR (shape 1): `packageModuleConst` — same `NewXxxProps` ctor-context
+  // bucket as `ctor-lowering.ts`.
   'packages/adapter-go-template/src/adapter/memo/memo-value.ts': { 'localConstants.find(': 1 },
-  'packages/adapter-jinja/src/adapter/jinja-adapter.ts': { staticLoopSourceBoundNames: 8, loopBoundNames: 12 },
+  // FLOOR (shape 1, already guarded): same `this.scope.isBound(trimmed)`
+  // shadow guard as `erb-adapter.ts` (#2221 — `resolveLiteralConst` /
+  // `resolveStaticRecordLiteral`'s established pattern).
   'packages/adapter-mojolicious/src/adapter/mojo-adapter.ts': {
     'localConstants.find(': 1,
-    staticLoopSourceBoundNames: 1,
-    loopBoundNames: 23,
   },
-  'packages/adapter-rust/src/adapter/minijinja-adapter.ts': { staticLoopSourceBoundNames: 8, loopBoundNames: 12 },
-  'packages/adapter-twig/src/adapter/twig-adapter.ts': { staticLoopSourceBoundNames: 8, loopBoundNames: 12 },
-  'packages/adapter-xslate/src/adapter/xslate-adapter.ts': { staticLoopSourceBoundNames: 8, loopBoundNames: 12 },
+  // FLOOR (shape 2): `generateSignalInitializers`'s reachability analysis
+  // for SSR no-op initializer dead-code elimination — module/component-level
+  // declaration reachability, unrelated to loop-row shadowing entirely.
   'packages/jsx/src/adapters/jsx-adapter.ts': { 'localConstants.find(': 1 },
+  // FLOOR (shape 2): resolves a `Record<T,string>[key]`-shaped indexed
+  // lookup's IDENT operand to a module-scope object-literal const for
+  // `renderToTest`'s union-semantics resolution — a component-level static
+  // analysis pass, not a loop-row shadow question.
   'packages/jsx/src/augment-inherited-props.ts': { 'localConstants.find(': 1 },
+  // FLOOR (shape 2): cross-IR CSS class-const resolution for the UnoCSS
+  // layer prefixer's transitive-reference walk — operates across whole
+  // components' `localConstants` lists, no loop-row scope involved.
   'packages/jsx/src/css-layer-prefixer.ts': { 'localConstants.find(': 1 },
-  'packages/jsx/src/debug.ts': { loopParams: 18 },
-  'packages/jsx/src/free-refs.ts': { 'localConstants.find(': 1, loopParams: 4 },
+  'packages/jsx/src/free-refs.ts': {
+    // FLOOR (shape 2): `resolveConstantInitializerRefs`'s transitive-taint
+    // expansion — resolves a local constant's OWN initializer by name to
+    // recurse into its free refs, not a loop-row shadow check.
+    'localConstants.find(': 1,
+    // FLOOR: the `BindingEnvironment.loopParams` field itself was RENAMED
+    // (Stage 4) to `loopValueBoundNames` (it carries `scope.valueBoundNames()`
+    // — the field name now says so). This single remaining occurrence is the
+    // rename's own historical-name mention in `loopValueBoundNames`'s
+    // docstring, matching the established convention elsewhere (e.g.
+    // `binding-scope.ts`'s own header keeps six `ctx.loopParams` mentions as
+    // migration history).
+    loopParams: 1,
+  },
+  // FLOOR (shape 3): `irToPlaceholderTemplate`'s loop-param accessor-rewrite
+  // spec forwarding — see the canonical docstring on
+  // `wrapExprWithLoopParams` in `ir-to-client-js/utils.ts`.
   'packages/jsx/src/ir-to-client-js/collect-elements.ts': { loopParams: 9 },
+  // FLOOR (shape 2): `computeCsrInlinability`'s fixed-point constant-chain
+  // inlining loop over `ctx.localConstants` — component-scope const
+  // resolution, not loop-row scope.
   'packages/jsx/src/ir-to-client-js/compute-inlinability.ts': { 'localConstants.find(': 1 },
+  // FLOOR (shape 3): event-delegation plan building deliberately does NOT
+  // pass a loop-param accessor-rewrite spec (see the file's own comments) —
+  // the remaining mentions are all in that reasoning, not device usage.
   'packages/jsx/src/ir-to-client-js/control-flow/plan/build-event-delegation.ts': { loopParams: 4 },
-  'packages/jsx/src/ir-to-client-js/html-template.ts': { loopParams: 16 },
+  // FLOOR (shape 3): `irToHtmlTemplate`/`irToPlaceholderTemplate`'s
+  // loop-param accessor-rewrite spec — see `ir-to-client-js/utils.ts`'s
+  // `wrapExprWithLoopParams` docstring (the canonical explanation, pointed
+  // to from this file's own function signature since Stage 4).
+  'packages/jsx/src/ir-to-client-js/html-template.ts': { loopParams: 17 },
+  // FLOOR (shape 1, already guarded): both `expandDynamicPropValue` and
+  // `expandConstantForReactivity` precede their `.find(` with
+  // `scope?.isBound(trimmedValue)` — see this file's own header comment
+  // (added Stage 1b) for the full SHADOW GUARD reasoning.
   'packages/jsx/src/ir-to-client-js/prop-handling.ts': { 'localConstants.find(': 2 },
-  'packages/jsx/src/ir-to-client-js/utils.ts': { loopParams: 3 },
-  'packages/jsx/src/jsx-to-ir.ts': { loopParams: 1 },
+  // FLOOR (shape 3): `wrapExprWithLoopParams` / `LoopParamSpec` — the
+  // canonical definition of the accessor-rewrite payload every other
+  // `loopParams`-named parameter in `ir-to-client-js/` forwards. See its
+  // docstring (added Stage 4) for the full shape-3 reasoning.
+  'packages/jsx/src/ir-to-client-js/utils.ts': { loopParams: 4 },
+  // `jsx-to-ir.ts` — MIGRATED to 0 in Stage 4: `makeBindingEnv`'s
+  // `loopParams: boundNames` field now reads `loopValueBoundNames:
+  // boundNames`, matching `free-refs.ts`'s renamed field. No entry needed
+  // (a missing key means an expected count of 0).
 }
 
 const SCOPE_MODULE_DIR = join(REPO_ROOT, 'packages', 'jsx', 'src', 'scope')

package/src/__tests__/component-type-parameters.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Regression test for #2573 (xyflow TS2304 family): a component function's
+ * own generic type parameters (`function Flow<NodeType, EdgeType>(...)`)
+ * were dropped from the emitted `.tsx` SSR template — the function
+ * signature came out as `function Flow(...)` even though its props type
+ * annotation (and often its body) kept referencing `NodeType`/`EdgeType`
+ * verbatim (`props: FlowComponentProps<NodeType, EdgeType>`,
+ * `createFlowStore<NodeType, EdgeType>(props)`). TypeScript then reported
+ * "Cannot find name 'NodeType'" (TS2304) at every such reference — the
+ * declaration that would have brought the name into scope was never
+ * emitted. Runtime output (client JS) was always correct; this is a
+ * type-level emission defect in the SSR template only.
+ *
+ * `IRMetadata.typeParameters` now carries the source's type parameter list
+ * verbatim (`node.getText()` per parameter, mirroring `ConstantInfo.
+ * typeAnnotation`'s #2589 precedent), and `HonoAdapter`/`TestAdapter` splice
+ * it between the function name and the parameter list.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { HonoAdapter } from '../../../../packages/adapter-hono/src/adapter/hono-adapter'
+
+describe('component type parameter preservation in emitted templates (#2573)', () => {
+  test('a generic function component keeps its type parameters on the emitted signature', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      interface NodeBase { id: string }
+      interface EdgeBase { id: string }
+      interface FlowProps<NodeType extends NodeBase, EdgeType extends EdgeBase> {
+        nodes: NodeType[]
+        edges: EdgeType[]
+      }
+
+      export function Flow<NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(
+        props: FlowProps<NodeType, EdgeType>,
+      ) {
+        const count = props.nodes.length + props.edges.length
+        return <div>{count}</div>
+      }
+    `
+
+    const result = compileJSX(source, 'Flow.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    expect(template.content).toContain(
+      'function Flow<NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase = EdgeBase>(',
+    )
+  })
+
+  test('a non-generic function component gains no type parameter clause', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      interface CardProps { title: string }
+      export function Card(props: CardProps) {
+        return <div>{props.title}</div>
+      }
+    `
+
+    const result = compileJSX(source, 'Card.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    expect(template.content).toContain('function Card(')
+    expect(template.content).not.toMatch(/function Card</)
+  })
+})

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

@@ -69,7 +69,16 @@ describe('CSR materialize template vs .map() preamble-local shadowing a module c
 
     // 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>`')
+    //
+    // The branch also carries a `bf-c="s0"` slot marker on both arms
+    // (#2596 follow-up): `label`'s initializer reads the real signal `on()`,
+    // so `markPreambleConditionalReactivity` now grants this conditional a
+    // slot id and the `reactive` flag it lacked before — the SAME
+    // observable-failure-mode class this file's docstring describes
+    // ("every row's branch condition evaluated the constant's fixed
+    // truthiness"), just for the signal dimension instead of the shadowing
+    // one. Nothing else about this fixture's shape changed.
+    expect(tpl).toContain('label ? `<span bf-c="s0">yes</span>` : `<span bf-c="s0">no</span>`')
     expect(tpl).not.toContain("('MODULE_CONST')")
     expect(tpl).not.toContain('MODULE_CONST')
   })

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

@@ -460,6 +460,7 @@ const ERROR_CODES_DOC_TOO_MINIMAL: Record<string, string> = {
   BF021: 'BF021 has multiple ❌ snippets in placeholder form (`.map(...)`) — covered concretely by `jsx-compatibility.md` tests; the doc-form snippets here remain placeholder',
   BF043: 'BF043 fires only for STATEFUL components (signals/memos/effects). The doc snippet `function Child({ count }: Props)` has no reactivity, so the check is correctly silent — doc snippet needs enrichment to be testable as-is',
   BF044: 'BF044 fires only when a real signal getter is bound. The doc snippet `<Child count={count} />` references an undeclared `count`, so the check is silent — doc snippet needs enrichment',
+  BF101: 'BF101 is raised by the non-JS template adapters\' own per-adapter checks (Go/Mojo/Xslate/… `renderLoop` / callback lowering), not by the shared `isSupported` gate every adapter shares — `TestAdapter` here is JS-runtime-style like Hono and executes both doc snippets verbatim, so the check is correctly silent. Covered concretely (compiled against the real 8 template adapters, with verbatim diagnostic text) by `jsx-compatibility.md`\'s doc-examples coverage and the `filter-nested-callback-predicate` / `filter-nested-find-predicate` / `static-array-from-props` adapter-conformance fixtures.',
 }
 
 // BFxxx codes that `errors.ts` defines but no production code in

package/src/__tests__/free-refs.test.ts

@@ -110,7 +110,7 @@ describe('resolveFreeRefs — kind resolution', () => {
     const env = {
       ...emptyEnv(),
       localConstants: [mkConst('item')],
-      loopParams: new Set(['item']),
+      loopValueBoundNames: new Set(['item']),
     }
     const refs = resolveFreeRefs(parseExpression('item'), env)
     expect(refs.find(r => r.name === 'item')?.kind).toBe('render-item')