@barefootjs/jsx 0.31.4 → 0.31.5

package/src/__tests__/signal-setter-updater-type.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Regression test for #2573 (chart TS7006 family): the SSR no-op signal
+ * setter stub was declared as `(..._args: any[]) => {}`. Calling it with
+ * an updater function — `setBars((prev) => [...prev, bar])` — puts that
+ * arrow in a rest-`any[]` argument position, not a function-typed one, so
+ * TypeScript has no contextual signature to infer the arrow's own
+ * parameter from and flags it implicit-any (TS7006). Runtime output
+ * (client JS) was always correct; this is a type-level emission defect in
+ * the SSR template only.
+ *
+ * The real `createSignal<T>` setter accepts `T | ((prev: T) => T)`
+ * (`packages/client/src/reactive.ts`'s `Signal<T>`). The stub now mirrors
+ * that signature whenever the signal's type is known (`SignalInfo.type`,
+ * the same field `needsTypeAssertion` already reads for the getter), so
+ * the updater arrow's parameter infers from the real element type.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { HonoAdapter } from '../../../../packages/adapter-hono/src/adapter/hono-adapter'
+
+describe('signal setter updater-function typing in emitted templates (#2573)', () => {
+  test('a typed signal gets an updater-aware setter stub', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      interface Bar { id: string; height: number }
+
+      export function Chart() {
+        const [bars, setBars] = createSignal<Bar[]>([])
+
+        // Called directly from the returned JSX (not from an onXxx handler
+        // prop, which SSR stubs to a no-op) so it — and the setter call
+        // inside it — stays reachable into the emitted template.
+        const addBar = (bar: Bar) => {
+          setBars((prev) => [...prev, bar])
+          return bars().length
+        }
+
+        return <div>{addBar({ id: 'a', height: 1 })}</div>
+      }
+    `
+
+    const result = compileJSX(source, 'Chart.tsx', { adapter: honoAdapter })
+    expect(result.errors).toHaveLength(0)
+
+    const template = result.files.find((f) => f.type === 'markedTemplate')!
+    expect(template).toBeDefined()
+    expect(template.content).toContain(
+      'const setBars: (valueOrFn: Bar[] | ((prev: Bar[]) => Bar[])) => void = () => {}',
+    )
+  })
+
+  test('a signal with no resolvable type keeps the untyped rest-args stub', () => {
+    const honoAdapter = new HonoAdapter()
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function Widget(props: { initial: unknown }) {
+        const [value, setValue] = createSignal(props.initial)
+
+        const reset = () => {
+          setValue(props.initial)
+          return value()
+        }
+
+        return <div>{String(reset())}</div>
+      }
+    `
+
+    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()
+    expect(template.content).toContain('const setValue = (..._args: any[]) => {}')
+  })
+})

package/src/adapters/jsx-adapter.ts

@@ -17,7 +17,7 @@ import { BF_SCOPE, BF_SLOT, BF_COND } from '@barefootjs/shared'
 import { BaseAdapter } from './interface.ts'
 import type { CallbackBodyAcceptor } from './interface.ts'
 import { ENV_SIGNAL_CLIENT_FACTORY } from './env-signal.ts'
-import { formatParamWithType, findReachableNames } from '../module-exports.ts'
+import { formatParamWithType, closeOverWritersOfMutableBindings } from '../module-exports.ts'
 import { extractFreeIdentifiersFromText } from '../ir-to-client-js/csr-substitute.ts'
 import { identifierPattern } from '../identifier-pattern.ts'
 
@@ -113,7 +113,15 @@ export abstract class JsxAdapter extends BaseAdapter {
     ]
 
     // Find reachable declarations via transitive dependency analysis
-    const reachable = findReachableNames(primaryRefText, declarations)
+    const reachable = closeOverWritersOfMutableBindings(
+      primaryRefText,
+      declarations,
+      new Set(
+        ir.metadata.localConstants
+          .filter(c => (c.declarationKind ?? 'const') !== 'const')
+          .map(c => c.name),
+      ),
+    )
 
     // Also check which signal setters are referenced
     const reachableBodies = [...reachable].map(name => {
@@ -168,7 +176,25 @@ export abstract class JsxAdapter extends BaseAdapter {
       if (signal.setter) {
         const setterUsed = identifierPattern(signal.setter).test(setterRefText)
         if (setterUsed) {
-          lines.push(`  const ${signal.setter} = (..._args: any[]) => {}`)
+          // The real `createSignal<T>` setter accepts `T | ((prev: T) =>
+          // T)` (`packages/client/src/reactive.ts`'s `Signal<T>`). The
+          // untyped `(..._args: any[]) => {}` stub gave every `setX((prev)
+          // => ...)` updater-function call site an `any[]`-typed argument
+          // position — not a function-typed one — so the arrow's own
+          // `prev` parameter had no contextual type to infer from and
+          // `tsc` flagged it implicit-any (TS7006, #2573 chart family).
+          // Mirror the real setter's signature whenever the signal's type
+          // is known, so updater-function callers keep their inference;
+          // fall back to the untyped stub only when it isn't (matches
+          // `needsTypeAssertion`'s `'unknown'` guard just above).
+          const setterType = preserveTypes && signal.type.kind !== 'unknown'
+            ? `(valueOrFn: ${signal.type.raw} | ((prev: ${signal.type.raw}) => ${signal.type.raw})) => void`
+            : null
+          lines.push(
+            setterType
+              ? `  const ${signal.setter}: ${setterType} = () => {}`
+              : `  const ${signal.setter} = (..._args: any[]) => {}`,
+          )
         }
       }
     }

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

@@ -16,6 +16,24 @@
  * degrades to the ALREADY-accepted residual (`+` falls back to numeric,
  * same as before #2212 for an unresolvable operand) rather than ever
  * producing silently-wrong output.
+ *
+ * #2482 (BindingScope) does NOT replace this: it answers "is NAME bound
+ * AT THIS POSITION", a live, position-accurate query built by walking
+ * INTO scopes during a render-time (or render-shaped) tree walk. This
+ * function answers a deliberately different, coarser question —
+ * "is NAME EVER a loop-bound name ANYWHERE in the component" — a single
+ * whole-component prepass run once at `generate()` entry, before any
+ * loop scope exists to thread. The two are complementary, not
+ * duplicative: swapping this for `BindingScope` would require re-deriving
+ * a position-accurate answer at every string-typed-operand call site,
+ * which is exactly the coarse-but-safe trade-off this function exists to
+ * avoid. Stays outside the `binding-scope-ratchet.test.ts` ledger for an
+ * incidental reason too — a lowercase-`l`-led spelling of this file's own
+ * export once lived as a per-adapter ref-counted-map field name (fully
+ * migrated away in an earlier #2482 stage) that the ledger's scan tracked;
+ * this function's own `collectLoopBoundNames` name is capitalized
+ * differently (a capital `L`) and so was never inside that scan's reach in
+ * the first place.
  */
 
 import type { ComponentIR, IRNode } from '../types.ts'

package/src/adapters/test-adapter.ts

@@ -164,7 +164,10 @@ export class TestAdapter extends JsxAdapter {
     // Module-export keyword belongs to the adapter: it knows the target language
     // and whether the source declared the component as exported.
     const exportPrefix = ir.metadata.isExported === false ? '' : 'export '
-    lines.push(`${exportPrefix}function ${name}(${fullPropsDestructure}${typeAnnotation}${noArgDefault}) {`)
+    // Carry the source component's own generic type parameters, if any
+    // (mirrors `HonoAdapter` — see `IRMetadata.typeParameters`'s docstring).
+    const typeParameters = ir.metadata.typeParameters ?? ''
+    lines.push(`${exportPrefix}function ${name}${typeParameters}(${fullPropsDestructure}${typeAnnotation}${noArgDefault}) {`)
 
     // Generate scope ID
     if (hasClientInteractivity) {

package/src/augment-inherited-props.ts

@@ -464,14 +464,26 @@ export function collectModuleStringConsts(
  * compile-time lookup (the icon registry's `strokePaths['chevron-down']`,
  * pagination's `variantClasses.ghost`; #1896 / #1897). Returns the
  * looked-up scalar, or `null` for any other shape so callers fall back
- * to their generic lowering. Shared by all three SSR template adapters;
+ * to their generic lowering. Shared by all seven template-string adapters;
  * the prop-KEYED variant of the pattern lives in `parseRecordIndexAccess`.
+ *
+ * `isShadowed` is REQUIRED (#2482 Stage 2) rather than left to caller
+ * discipline: an enclosing loop callback's own param/index/destructure/
+ * preamble binding of the same name as `objectName` (`.map((cfg) =>
+ * <li>{cfg.x}</li>)` shadowing a module `const cfg = {…}`) must resolve to
+ * the ROW value, not the outer const's member — every call site used to
+ * check this itself, against its own ad-hoc per-adapter shadow-name
+ * bookkeeping, with no static guarantee a new caller wouldn't forget it.
+ * Pass `scope.isBound` (or `scope.asShadowPredicate()`) from the caller's
+ * threaded `BindingScope`.
  */
 export function lookupStaticRecordLiteral(
   objectName: string,
   key: string,
   constants: IRMetadata['localConstants'] | undefined,
+  isShadowed: (name: string) => boolean,
 ): { kind: 'string' | 'number'; text: string } | null {
+  if (isShadowed(objectName)) return null
   const constInfo = (constants ?? []).find(c => c.name === objectName && c.isModule)
   if (constInfo?.value === undefined) return null
   const sf = ts.createSourceFile(

package/src/compiler.ts

@@ -624,6 +624,23 @@ function compileMultipleComponents(
 // Helpers
 // =============================================================================
 
+/**
+ * Verbatim text of the component function's own generic type parameter
+ * list (`<NodeType extends NodeBase = NodeBase, EdgeType extends EdgeBase
+ * = EdgeBase>`), or `null` when the component isn't generic. Source text
+ * per parameter (`node.getText(sourceFile)`), not a re-printed AST, so
+ * constraints/defaults/comments round-trip exactly like `ConstantInfo.
+ * typeAnnotation` does for `let` (#2589) — see `IRMetadata.typeParameters`.
+ */
+function componentTypeParametersText(
+  componentNode: ts.FunctionDeclaration | ts.ArrowFunction | null,
+  sourceFile: ts.SourceFile,
+): string | null {
+  const typeParameters = componentNode?.typeParameters
+  if (!typeParameters || typeParameters.length === 0) return null
+  return `<${typeParameters.map(p => p.getText(sourceFile)).join(', ')}>`
+}
+
 export function buildMetadata(
   ctx: ReturnType<typeof analyzeComponent>,
 ): IRMetadata {
@@ -634,6 +651,7 @@ export function buildMetadata(
     isClientComponent: ctx.hasUseClientDirective,
     typeDefinitions: ctx.typeDefinitions,
     propsType: ctx.propsType,
+    typeParameters: componentTypeParametersText(ctx.componentNode, ctx.sourceFile),
     propsParams: ctx.propsParams,
     propsObjectName: ctx.propsObjectName,
     restPropsName: ctx.restPropsName,

package/src/debug.ts

@@ -30,6 +30,7 @@ import type { WrapReason } from './ir-to-client-js/reactivity.ts'
 import { decideWrapFromAstFlags } from './ir-to-client-js/reactivity.ts'
 import { tokenContainsIdent } from './ir-to-client-js/utils.ts'
 import { identifierCallPattern } from './identifier-pattern.ts'
+import { BindingScope } from './scope/binding-scope.ts'
 
 // =============================================================================
 // Types
@@ -360,7 +361,7 @@ export function buildGraphFromIR(ir: ComponentIR): ComponentGraph {
 
   // Collect DOM bindings from IR tree
   const domBindings: DomBinding[] = []
-  collectDomBindings(ir.root, domBindings, signalGetters, memoNames, undefined, new Set(), exprReadsProp)
+  collectDomBindings(ir.root, domBindings, signalGetters, memoNames, undefined, BindingScope.EMPTY, exprReadsProp)
 
   // Build consumer lists for signals
   const signalConsumers = new Map<string, string[]>()
@@ -1676,30 +1677,41 @@ function collectDomBindings(
   signalGetters: Set<string>,
   memoNames: Set<string>,
   parentTag?: string,
-  // Loop-param names in scope (#1690, #1795 Phase 2). Inside a `map(it => …)`
+  // Loop-param names in scope (#1690, #1795 Phase 2; threaded via the shared
+  // `BindingScope` service since #2482 Stage 4). Inside a `map(it => …)`
   // body the emitter rewrites every `it.x` read into a reactive accessor and
   // wraps the binding in `createEffect`, yet `it` is neither a signal nor a
   // memo — so without this context loop-child text / attribute bindings are
   // invisible to the graph. When a binding expression references one of these
   // names it is treated as reactive (matching the emitter's gate), giving the
   // profiler a `domBinding` (slotId + loc) to resolve `<Comp>#binding:<slotId>`.
-  loopParams: Set<string> = new Set(),
+  // This is the REACTIVITY / SLOT-ID CLASSIFIER consumer class (see
+  // `BindingScope.valueBoundNames`'s docstring) — reads `valueBoundNames()`,
+  // not `boundNames()`.
+  scope: BindingScope = BindingScope.EMPTY,
   // Predicate: does an attribute expression read a component prop? Mirrors the
   // emitter's `needsEffectWrapper` prop detection so a prop-driven attribute
   // (wrapped in `createEffect` at codegen, hence emitting `#binding:<slot>`) is
   // tracked here too — otherwise its profiler id resolves to `(unresolved)`.
   readsProp: (expr: string, freeIds?: ReadonlySet<string>) => boolean = () => false,
 ): void {
+  const boundNames = scope.valueBoundNames()
   // Does a loop-child binding read a loop param (or index)? Use the analyzer's
   // lexer-resolved metadata, NOT a raw-string regex — so a param name that only
   // appears inside a string literal (index `i` vs `'i'`) is not mistaken for a
   // reactive read. Text expressions carry `origin.freeRefs` (a `render-item`
   // kind == map-callback param); attributes carry `freeIdentifiers` (bare
   // identifier set). This matches the emitter's actual loop-param gate.
+  // Set-intersection test without spreading into an array — these run per
+  // node in the graph walk, so avoid the per-call allocation.
+  const setSomeIn = (names: ReadonlySet<string>, other: ReadonlySet<string>): boolean => {
+    for (const n of names) if (other.has(n)) return true
+    return false
+  }
   const exprReadsLoopParam = (n: IRExpression): boolean =>
-    loopParams.size > 0 && (n.origin?.freeRefs?.some(r => loopParams.has(r.name)) ?? false)
+    boundNames.size > 0 && (n.origin?.freeRefs?.some(r => boundNames.has(r.name)) ?? false)
   const attrReadsLoopParam = (free: ReadonlySet<string> | undefined): boolean =>
-    loopParams.size > 0 && free !== undefined && [...loopParams].some(p => free.has(p))
+    boundNames.size > 0 && free !== undefined && setSomeIn(boundNames, free)
   switch (node.type) {
     case 'element': {
       // Dynamic attribute bindings (style, class, aria-*, data-*, etc.)
@@ -1713,7 +1725,7 @@ function collectDomBindings(
         // `key` is consumed by the loop's keyFn, never emitted as an attribute
         // effect — skip it inside loops so a `key={it.id}` read isn't mistaken
         // for a reactive binding (matches `collectLoopChildBindings`).
-        if (attr.name === 'key' && loopParams.size > 0) continue
+        if (attr.name === 'key' && boundNames.size > 0) continue
         const expr = attrValueToString(attr.value)
         if (!expr) continue
         const deps = extractReactiveDeps(expr, signalGetters, memoNames)
@@ -1756,7 +1768,7 @@ function collectDomBindings(
       }
       // Recurse — pass element tag as parent context for text bindings
       for (const child of node.children) {
-        collectDomBindings(child, bindings, signalGetters, memoNames, node.tag, loopParams, readsProp)
+        collectDomBindings(child, bindings, signalGetters, memoNames, node.tag, scope, readsProp)
       }
       break
     }
@@ -1794,7 +1806,7 @@ function collectDomBindings(
       // (the emitter wraps its `insert()` in a per-item effect) even though the
       // param is neither signal nor memo. Use the resolved `origin.freeRefs`.
       const loopReactive =
-        loopParams.size > 0 && (node.origin?.freeRefs?.some(r => loopParams.has(r.name)) ?? false)
+        boundNames.size > 0 && (node.origin?.freeRefs?.some(r => boundNames.has(r.name)) ?? false)
       if ((decision.wrap || loopReactive) && node.slotId) {
         const deps = extractReactiveDeps(node.condition, signalGetters, memoNames)
         bindings.push({
@@ -1813,8 +1825,8 @@ function collectDomBindings(
           jsxPreview: `{${truncateExpr(node.condition)} ? ... : ...}`,
         })
       }
-      collectDomBindings(node.whenTrue, bindings, signalGetters, memoNames, parentTag, loopParams, readsProp)
-      collectDomBindings(node.whenFalse, bindings, signalGetters, memoNames, parentTag, loopParams, readsProp)
+      collectDomBindings(node.whenTrue, bindings, signalGetters, memoNames, parentTag, scope, readsProp)
+      collectDomBindings(node.whenFalse, bindings, signalGetters, memoNames, parentTag, scope, readsProp)
       break
     }
     case 'loop': {
@@ -1828,9 +1840,9 @@ function collectDomBindings(
         // An inner loop whose array reads an outer loop param (`r.tags.map(...)`)
         // is reactive per item — use the resolved `arrayFreeIdentifiers`.
         const loopReactive =
-          loopParams.size > 0 &&
+          boundNames.size > 0 &&
           node.arrayFreeIdentifiers !== undefined &&
-          [...loopParams].some(p => node.arrayFreeIdentifiers!.has(p))
+          setSomeIn(boundNames, node.arrayFreeIdentifiers)
         const isReactive = deps.length > 0 || node.callsReactiveGetters === true || loopReactive
         const isFallback = !isReactive && node.hasFunctionCalls === true
         if (isReactive || isFallback) {
@@ -1859,12 +1871,13 @@ function collectDomBindings(
           })
         }
       }
-      // Loop-param names enter scope for the children (#1690, #1795 Phase 2).
-      const childLoopParams = new Set(loopParams)
-      for (const p of extractLoopParamNames(node.param, node)) childLoopParams.add(p)
-      if (node.index) childLoopParams.add(node.index)
+      // Loop-param names enter scope for the children (#1690, #1795 Phase 2),
+      // via the same `BindingScope.enterLoopRow` the emitter uses — `IRLoop`
+      // already satisfies `LoopBindingSource` structurally (`param`/`index`/
+      // `paramBindings`/`preamble`), so no bespoke Set bookkeeping is needed.
+      const childScope = scope.enterLoopRow(node)
       for (const child of node.children) {
-        collectDomBindings(child, bindings, signalGetters, memoNames, parentTag, childLoopParams, readsProp)
+        collectDomBindings(child, bindings, signalGetters, memoNames, parentTag, childScope, readsProp)
       }
       break
     }
@@ -1903,21 +1916,21 @@ function collectDomBindings(
         }
       }
       for (const child of node.children) {
-        collectDomBindings(child, bindings, signalGetters, memoNames, parentTag, loopParams, readsProp)
+        collectDomBindings(child, bindings, signalGetters, memoNames, parentTag, scope, readsProp)
       }
       break
     }
     case 'fragment':
     case 'provider': {
       for (const child of node.children) {
-        collectDomBindings(child, bindings, signalGetters, memoNames, parentTag, loopParams, readsProp)
+        collectDomBindings(child, bindings, signalGetters, memoNames, parentTag, scope, readsProp)
       }
       break
     }
     case 'if-statement': {
-      collectDomBindings(node.consequent, bindings, signalGetters, memoNames, parentTag, loopParams, readsProp)
+      collectDomBindings(node.consequent, bindings, signalGetters, memoNames, parentTag, scope, readsProp)
       if (node.alternate) {
-        collectDomBindings(node.alternate, bindings, signalGetters, memoNames, parentTag, loopParams, readsProp)
+        collectDomBindings(node.alternate, bindings, signalGetters, memoNames, parentTag, scope, readsProp)
       }
       break
     }

package/src/free-refs.ts

@@ -41,14 +41,23 @@ export interface BindingEnvironment {
   localFunctions: readonly FunctionInfo[]
   imports: readonly ImportInfo[]
   ambientGlobals: ReadonlySet<string>
-  /** Active `.map()` callback parameter names — present inside loop bodies. */
-  loopParams?: ReadonlySet<string>
+  /**
+   * Active `.map()` callback VALUE-bound names (item/index/destructure —
+   * excludes preamble locals and callback params) — present inside loop
+   * bodies. Named after, and fed from, `BindingScope.valueBoundNames()`
+   * (#2482 Stage 4 rename from `loopParams`, which predated the shared
+   * `BindingScope` service and named the mechanism, not the query). This
+   * is the REACTIVITY / SLOT-ID CLASSIFIER consumer class — see that
+   * method's docstring for why it must stay `valueBoundNames`, not
+   * `boundNames`.
+   */
+  loopValueBoundNames?: ReadonlySet<string>
   checker: ts.TypeChecker | null
 }
 
 /**
  * Per-environment cache for the binding map. `BindingEnvironment` identity
- * is stable per (analyzer, loopParams snapshot) — `jsx-to-ir.ts` memoizes
+ * is stable per (analyzer, loopValueBoundNames snapshot) — `jsx-to-ir.ts` memoizes
  * `makeBindingEnv` so the same object is reused across every
  * `resolveFreeRefs` call within a loop scope. With N expressions per
  * component and M bindings per env, this drops binding-table construction
@@ -114,8 +123,8 @@ function buildBindingMap(env: BindingEnvironment): Map<string, BindingKind> {
     map.set(m.name, 'memo-getter')
   }
   // Highest precedence — innermost scope.
-  if (env.loopParams) {
-    for (const name of env.loopParams) map.set(name, 'render-item')
+  if (env.loopValueBoundNames) {
+    for (const name of env.loopValueBoundNames) map.set(name, 'render-item')
   }
 
   _bindingMapCache.set(env, map)

package/src/ir-to-client-js/collect-elements.ts

@@ -5,10 +5,11 @@
 import { type IRNode, type IRElement, type IRComponent, type IRLoop, type IRProp, pickAttrMetaFromIR } from '../types.ts'
 import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, LoopOffset, NestedLoop } from './types.ts'
 import { attrValueToString, freeIdsFromRefs, quotePropName, PROPS_PARAM } from './utils.ts'
-import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings, buildLoopRowScope } from './reactivity.ts'
+import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings, buildLoopRowScope, anyNameIn } from './reactivity.ts'
 import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, renderFlatMapClientBody, renderFlatMapProjectionClientBody, flatMapCallbackHasKeyedLeaf, type SkeletonSlotPaths } from './html-template.ts'
 import { templateRootIsSvg } from './control-flow/stringify/template-parse.ts'
 import { expandDynamicPropValue, expandConstantForReactivity } from './prop-handling.ts'
+import { extractFreeIdentifiersFromText } from './csr-substitute.ts'
 import { walkIR, stopAt } from './walker.ts'
 import { buildLoopChainExpr } from '../loop-chain.ts'
 import { identifierPattern } from '../identifier-pattern.ts'
@@ -1428,9 +1429,22 @@ export function collectLoopChildConditionals(
       // paying for constant expansion — matches the legacy short-circuit.
       if (!n.reactive && !refsLoopParamInSource) return
       const expanded = expandConstantForReactivity(n.condition, ctx, sourceFreeIds, scope)
+      // A `.map()` callback preamble local (#2596, twin of
+      // `collectLoopChildReactiveAttrs`'s `readsPreamble` #2447). Phase 1
+      // already proved this condition reactive when it's set (`n.reactive`
+      // came from `markPreambleConditionalReactivity`, gated on the local's
+      // OWN initializer reading a signal) — `classifyReactivity` below
+      // cannot independently confirm that: `expandConstantForReactivity`
+      // leaves a preamble-bound identifier like `label` unexpanded on
+      // purpose (the #2482 Stage 1b shadow guard, `scope.isBound`), so the
+      // raw token never string-matches a signal/memo/prop pattern.
+      const readsPreamble =
+        preambleNames !== undefined &&
+        preambleNames.size > 0 &&
+        anyNameIn(expanded.freeIds ?? extractFreeIdentifiersFromText(expanded.expr), preambleNames)
       // Loop-param conditionals are reactive via per-item signal accessors;
       // classifyReactivity sees both paths (signal/memo/prop + loop-param).
-      if (classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind === 'none') return
+      if (!readsPreamble && classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind === 'none') return
 
       const loopParamsForCond = loopParam
         ? [{ param: loopParam, bindings: loopParamBindings }]
@@ -1449,6 +1463,7 @@ export function collectLoopChildConditionals(
         whenTrue: summarizeLoopChildBranch(n.whenTrue, ctx, siblingOffsets, loopParam, loopParamBindings, preambleNames, loopIndex),
         whenFalse: summarizeLoopChildBranch(n.whenFalse, ctx, siblingOffsets, loopParam, loopParamBindings, preambleNames, loopIndex),
         ...(expanded.freeIds !== undefined && { conditionFreeIdentifiers: expanded.freeIds }),
+        ...(readsPreamble && { readsPreamble: true }),
       })
     },
   })

package/src/ir-to-client-js/control-flow/plan/build-reactive-effects.ts

@@ -112,6 +112,7 @@ export function buildReactiveEffectsPlan(
         whenFalseTemplateHtml: addCondAttrToTemplate(wrap(cond.whenFalseHtml), cond.slotId),
         whenTrueArm: buildOuterArm(cond.whenTrue, wrap, loopParam, loopParamBindings, profileComponentName),
         whenFalseArm: buildOuterArm(cond.whenFalse, wrap, loopParam, loopParamBindings, profileComponentName),
+        ...(cond.readsPreamble && { readsPreamble: true }),
       })
     }
   }

package/src/ir-to-client-js/control-flow/plan/reactive-effects.ts

@@ -62,6 +62,13 @@ export interface NestedConditionalPlan {
   whenFalseTemplateHtml: string
   whenTrueArm: LoopChildArmPlan
   whenFalseArm: LoopChildArmPlan
+  /**
+   * `wrappedCondition` reads a `.map()` callback preamble local (#2596,
+   * twin of `ReactiveAttrEffect.readsPreamble`) — the stringifier must run
+   * the row's preamble ahead of evaluating the condition getter passed to
+   * `insert()`; the local isn't otherwise in scope there.
+   */
+  readsPreamble?: boolean
 }
 
 export interface ReactiveEffectsPlan {

package/src/ir-to-client-js/control-flow/stringify/reactive-effects.ts

@@ -140,7 +140,7 @@ export function stringifyReactiveEffects(
   // from the attrs/texts/regions merge above (its own per-branch disposable
   // effects), so it's untouched by row-granularity consolidation.
   for (const cond of conditionals) {
-    emitOuterConditional(lines, indent, elVar, cond, pc)
+    emitOuterConditional(lines, indent, elVar, cond, pc, mapPreambleWrapped)
   }
 }
 
@@ -342,12 +342,22 @@ function emitOuterConditional(
   elVar: string,
   cond: NestedConditionalPlan,
   pc: string | undefined,
+  mapPreambleWrapped: string | undefined,
 ): void {
   const armIndent = `${indent}    `
 
   // Body-form arrows so live `Node` returns from Child-position
   // interpolations route through `__bfSlot` and survive the splice (#1213).
-  lines.push(`${indent}insert(${elVar}, '${cond.slotId}', () => ${cond.wrappedCondition}, {`)
+  // A condition reading a preamble local (#2596) needs the preamble re-run
+  // INSIDE the getter — `insert()` re-invokes this closure on every
+  // dependency change to decide the branch, and the local isn't otherwise in
+  // scope here (it's a plain per-row `const`, not a signal `insert()` can see
+  // through on its own). Same treatment as `readsPreamble` attrs
+  // (`emitAttrUpdate`'s callers) get ahead of their own write.
+  const conditionGetter = cond.readsPreamble && mapPreambleWrapped
+    ? `() => { ${mapPreambleWrapped}; return (${cond.wrappedCondition}) }`
+    : `() => ${cond.wrappedCondition}`
+  lines.push(`${indent}insert(${elVar}, '${cond.slotId}', ${conditionGetter}, {`)
   lines.push(`${indent}  template: () => { const __slots = []; return { html: \`${cond.whenTrueTemplateHtml}\`, slots: __slots } },`)
   lines.push(`${indent}  bindEvents: (__branchScope, { isFirstRun: __bfFirstRun = false } = {}) => {`)
   stringifyLoopChildArm(lines, cond.whenTrueArm, armIndent, pc)

package/src/ir-to-client-js/html-template.ts

@@ -729,6 +729,11 @@ function escapeLeafTextExpressions(ir: IRNode): IRNode {
   }
 }
 
+// `loopParams` here is the accessor-rewrite spec list `wrapExprWithLoopParams`
+// consumes, not a `BindingScope`-trackable name set — see that function's
+// docstring (`ir-to-client-js/utils.ts`) for why this stays outside #2482's
+// migration (it's the client-JS-emitter twin of the Go adapter's
+// `loopBindingStack`).
 export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>, branchSlotsVar?: string, inHoistedChildren = false): string {
   const recurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, inHoistedChildren)
   const wrapExpr = (expr: string) => wrapExprWithLoopParams(expr, loopParams)

package/src/ir-to-client-js/reactivity.ts

@@ -671,8 +671,10 @@ export function collectLoopChildReactiveTexts(
  * `loopIndex` (Copilot review on #2595): see `collectLoopChildReactiveTexts`.
  */
 /** Does any name in `names` appear in `set`? Iterates rather than
- *  spreading — this runs per attribute (Copilot review). */
-function anyNameIn(names: Iterable<string>, set: ReadonlySet<string>): boolean {
+ *  spreading — this runs per attribute (Copilot review). Exported for
+ *  `collectLoopChildConditionals`'s `readsPreamble` check (#2596), the
+ *  condition-position twin of the attr check just below this uses it for. */
+export function anyNameIn(names: Iterable<string>, set: ReadonlySet<string>): boolean {
   for (const n of names) if (set.has(n)) return true
   return false
 }

package/src/ir-to-client-js/types.ts

@@ -578,6 +578,22 @@ export interface LoopChildConditional {
    * constants' own `freeIdentifiers`.
    */
   conditionFreeIdentifiers?: ReadonlySet<string>
+  /**
+   * `condition` references a `.map()` callback preamble-declared name
+   * (#2596, twin of `LoopChildReactiveAttr.readsPreamble` #2447) — the
+   * emitter must run the preamble ahead of evaluating the condition getter
+   * passed to `insert()`, since the local is not otherwise in scope there.
+   * Set whenever the condition mentions ANY preamble-declared name
+   * (`preambleNamesOf`), regardless of why the conditional was classified
+   * reactive — the scope obligation is the same either way. Whether the
+   * conditional is wired reactive AT ALL is the separate, stricter Phase-1
+   * question (`IRLoop.preamble.reactiveNames` via
+   * `markPreambleConditionalReactivity`, plus the ordinary signal/prop
+   * classifiers); `classifyReactivity` can't answer it from the token
+   * alone because `expandConstantForReactivity`'s shadow guard leaves a
+   * preamble-bound identifier unexpanded on purpose (#2482 Stage 1b).
+   */
+  readsPreamble?: boolean
 }
 
 export interface TopLevelLoop extends LoopCore {

package/src/ir-to-client-js/utils.ts

@@ -698,6 +698,21 @@ export interface LoopParamSpec {
  * avoiding post-hoc regex replacement on full template strings.
  *
  * Accepts either a bare param name or a spec carrying destructure bindings.
+ *
+ * #2482: this `loopParams` parameter (and the same-named param on
+ * `irToHtmlTemplate` / `irToPlaceholderTemplate` in `html-template.ts`,
+ * threaded through `collect-elements.ts` / `build-event-delegation.ts`) is
+ * NOT one of the ratchet's tracked ad-hoc scope devices, even though the
+ * ledger's textual pattern happens to match its spelling. `BindingScope`
+ * answers EXISTENCE/kind/depth queries about bound names; this ordered
+ * `ReadonlyArray<string | LoopParamSpec>` instead carries the ACCESSOR-
+ * REWRITE payload for outermost-to-innermost text substitution
+ * (`item` → `__bfItem().path`) — a rendering/codegen concern `BindingScope`
+ * has no field for by design, the client-JS-emitter twin of the Go
+ * adapter's `loopBindingStack` (see that field's docstring on
+ * `GoTemplateAdapter`). Order matters here (each nesting level's wrap
+ * composes over the previous), which is exactly what a scope EXISTENCE
+ * stack does not model.
  */
 export function wrapExprWithLoopParams(expr: string, loopParams?: ReadonlyArray<string | LoopParamSpec>): string {
   if (!loopParams) return expr