@barefootjs/jsx 0.31.3 → 0.31.5

package/src/identifier-pattern.ts

@@ -0,0 +1,79 @@
+/**
+ * Single door for building "does this expression text reference identifier
+ * X?" regexes (#2592).
+ *
+ * The naive `new RegExp(`\\b${name}\\b`)` idiom used throughout the compiler
+ * breaks for `$`-containing identifiers (legal in JS: `$item`, `item$`,
+ * `a$b`) in two independent ways:
+ *
+ *   1. Unescaped: an interpolated `$` is a regex metacharacter (end-of-
+ *      input/line anchor), so `\b$item\b` / `\ba$b\b` can (almost) never
+ *      match mid-string — false negative.
+ *   2. Even escaped, `\b` requires a `\w`/non-`\w` transition and `$` is
+ *      not `\w` (`[A-Za-z0-9_]`) — so `\b\$item\b` still fails to match the
+ *      leading boundary in `($item)` (both `(` and `$` are non-word, so no
+ *      transition occurs there).
+ *
+ * `identifierPattern` / `identifierCallPattern` fix both: the identifier
+ * text is escaped before interpolation, and the boundary is asserted with
+ * lookaround against `\p{ID_Continue}` (Unicode "can continue an
+ * identifier") unioned with `$`, so `$` is correctly treated as
+ * identifier-like on both sides of the match.
+ *
+ * Scope: these remain the same *bounded lexical heuristic* the compiler has
+ * always used for expression-text scanning (not a general JS/TS parse —
+ * see CLAUDE.md's structural-parsing rule, which does not apply to this
+ * class of check). This module only fixes the `$` boundary bug; it does not
+ * change what the heuristic considers a "reference" (string literals,
+ * comments, and member-access tails are still opaque to it — callers that
+ * need that precision use `tokenContainsIdent` / `node.freeIdentifiers`
+ * instead, per #1267).
+ */
+
+// Duplicate regex flags throw at construction ('gu' + 'u' -> SyntaxError),
+// so `u` is added only when the caller didn't already pass it.
+function withUnicodeFlag(flags: string): string {
+  return flags.includes('u') ? flags : `${flags}u`
+}
+
+/** Escape regex metacharacters in a literal identifier before interpolation. */
+export function escapeIdentifierForRegex(name: string): string {
+  return name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Lookaround fragments asserting "not preceded/followed by an identifier
+ * continuation character (including `$`)". `$` is a legal identifier char
+ * in JS but is not `\p{ID_Continue}`, so it's unioned in explicitly.
+ *
+ * Exported for the few call sites that must splice extra assertions
+ * between the identifier and the trailing boundary (e.g. "not followed by
+ * a call" as well as "not followed by an identifier char") — compose with
+ * these fragments rather than reintroducing a bare `\b`.
+ */
+export const ID_BOUNDARY_BEFORE = '(?<![\\p{ID_Continue}$])'
+export const ID_BOUNDARY_AFTER = '(?![\\p{ID_Continue}$])'
+
+/**
+ * Regex matching a standalone reference to identifier `name` — the `$`-safe
+ * replacement for `new RegExp(`\\b${name}\\b`)`. Always carries the `u`
+ * (unicode) flag, required for `\p{ID_Continue}`; pass additional flags
+ * (e.g. `'g'` for `String.replace`/`matchAll` substitution sites) via
+ * `flags`.
+ */
+export function identifierPattern(name: string, flags = ''): RegExp {
+  const esc = escapeIdentifierForRegex(name)
+  return new RegExp(`${ID_BOUNDARY_BEFORE}${esc}${ID_BOUNDARY_AFTER}`, withUnicodeFlag(flags))
+}
+
+/**
+ * Regex matching identifier `name` used in call position (`name(...)`,
+ * allowing whitespace before the paren) — the `$`-safe replacement for
+ * `new RegExp(`\\b${name}\\s*\\(`)`. No trailing boundary assertion is
+ * needed: `\s`/`(` are already not `\p{ID_Continue}`/`$`, so they can't be
+ * mistaken for a continuation of `name`.
+ */
+export function identifierCallPattern(name: string, flags = ''): RegExp {
+  const esc = escapeIdentifierForRegex(name)
+  return new RegExp(`${ID_BOUNDARY_BEFORE}${esc}\\s*\\(`, withUnicodeFlag(flags))
+}

package/src/index.ts

@@ -89,7 +89,7 @@ export type {
 } from './adapters/interface.ts'
 export { JsxAdapter } from './adapters/jsx-adapter.ts'
 export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
-export { rewriteImportsForTemplate } from './adapters/template-imports.ts'
+export { rewriteImportsForTemplate, rewriteDynamicImportsInSource } from './adapters/template-imports.ts'
 export { emitParsedExpr, groupBinaryOperand, isStringTypedOperand, isStringConcatBinary } from './adapters/parsed-expr-emitter.ts'
 export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
 export { collectLoopBoundNames } from './adapters/loop-bound-names.ts'

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

@@ -5,12 +5,14 @@
 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 } 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'
 
 /** Expressions that render nothing (0 DOM nodes) — `&&` / `?:` empty branches. */
 const EMPTY_RENDER_EXPRS = new Set(['null', 'undefined', 'false', "''", '""', '``'])
@@ -311,7 +313,7 @@ export function collectInnerLoops(
         const template = n.children.map(c => irToPlaceholderTemplate(c, undefined, emitDepth, loopParamsForTemplate)).join('')
         // Check if array expression references the outer loop param
         const refsOuter = outerLoopParam
-          ? new RegExp(`\\b${outerLoopParam}\\b`).test(n.array)
+          ? identifierPattern(outerLoopParam).test(n.array)
           : false
         // Per-item bindings for inner loop body, collected uniformly when
         // ctx is available: reactiveTexts / reactiveAttrs / refs are each
@@ -332,8 +334,8 @@ export function collectInnerLoops(
         const innerPreambleNames = preambleNamesOf(n)
         if (ctx) {
           for (const child of n.children) {
-            bindings.reactiveTexts.push(...collectLoopChildReactiveTexts(child, ctx, n.param, n.paramBindings))
-            bindings.reactiveAttrs.push(...collectLoopChildReactiveAttrs(child, ctx, n.param, n.paramBindings, false, innerPreambleNames))
+            bindings.reactiveTexts.push(...collectLoopChildReactiveTexts(child, ctx, n.param, n.paramBindings, false, innerPreambleNames, n.index))
+            bindings.reactiveAttrs.push(...collectLoopChildReactiveAttrs(child, ctx, n.param, n.paramBindings, false, innerPreambleNames, n.index))
             bindings.refs.push(...collectLoopChildRefs(child))
           }
         }
@@ -375,6 +377,8 @@ export function collectInnerLoops(
               siblingOffsets,
               n.param,
               n.paramBindings,
+              innerPreambleNames,
+              n.index,
             ))
           }
         }
@@ -671,7 +675,7 @@ export function collectElements(
       const childHandlers: string[] = []
       const bindings = projectionInner
         ? emptyLoopChildBindings()
-        : collectLoopChildBindings(l.children, ctx, siblingOffsets, l.param, l.paramBindings, preambleNamesOf(l))
+        : collectLoopChildBindings(l.children, ctx, siblingOffsets, l.param, l.paramBindings, preambleNamesOf(l), l.index)
       if (!projectionInner) {
         for (const child of l.children) {
           childHandlers.push(...collectEventHandlersFromIR(child))
@@ -1146,7 +1150,7 @@ function collectBranchLoops(
       // which caused reactive reads inside simple loop bodies to silently
       // no-op for existing items.
       const branchBindings = ctx && !projectionInner
-        ? collectLoopChildBindings(n.children, ctx, siblingOffsets, n.param, n.paramBindings, preambleNamesOf(n))
+        ? collectLoopChildBindings(n.children, ctx, siblingOffsets, n.param, n.paramBindings, preambleNamesOf(n), n.index)
         : emptyLoopChildBindings()
 
       loops.push({
@@ -1346,6 +1350,12 @@ export function collectLoopChildBindings(
    * `collectLoopChildReactiveAttrs`. Omitted for a loop with no preamble.
    */
   preambleNames?: ReadonlySet<string>,
+  /**
+   * The loop's index param name (`.map((item, i) => ...)`'s `i`), when
+   * present — folded into the shadow guard (Copilot review on #2595) so
+   * an index-shadowing const doesn't get const-folded either.
+   */
+  loopIndex?: string | null,
 ): LoopChildBindings {
   const bindings = emptyLoopChildBindings()
   for (const child of children) {
@@ -1355,10 +1365,10 @@ export function collectLoopChildBindings(
     // `collectLoopChildConditionals`, which gives each its own insert() +
     // arm-scoped attrs/texts (`LoopChildBranchSummary.reactiveAttrs` /
     // `.reactiveTexts`) — descending into them here too would double-bind.
-    bindings.reactiveAttrs.push(...collectLoopChildReactiveAttrs(child, ctx, loopParam, loopParamBindings, true, preambleNames))
-    bindings.reactiveTexts.push(...collectLoopChildReactiveTexts(child, ctx, loopParam, loopParamBindings, true))
+    bindings.reactiveAttrs.push(...collectLoopChildReactiveAttrs(child, ctx, loopParam, loopParamBindings, true, preambleNames, loopIndex))
+    bindings.reactiveTexts.push(...collectLoopChildReactiveTexts(child, ctx, loopParam, loopParamBindings, true, preambleNames, loopIndex))
     bindings.refs.push(...collectLoopChildRefs(child))
-    bindings.conditionals.push(...collectLoopChildConditionals(child, ctx, siblingOffsets, loopParam, loopParamBindings))
+    bindings.conditionals.push(...collectLoopChildConditionals(child, ctx, siblingOffsets, loopParam, loopParamBindings, preambleNames, loopIndex))
   }
   return bindings
 }
@@ -1369,8 +1379,24 @@ export function collectLoopChildConditionals(
   siblingOffsets: Map<IRLoop, IRNode[]>,
   loopParam?: string,
   loopParamBindings?: readonly import('../types.ts').LoopParamBinding[],
+  /**
+   * The enclosing loop's `.map()` callback preamble locals (#2447), when
+   * known — folded into the `expandConstantForReactivity` shadow guard
+   * (#2482 Stage 1b) so a preamble local shadowing a component/module
+   * const doesn't get const-folded into the condition, which would
+   * corrupt `classifyReactivity`'s verdict below (a substituted literal
+   * reads as "not reactive," silently freezing the branch at its initial
+   * value instead of wiring an `insert()`).
+   */
+  preambleNames?: ReadonlySet<string>,
+  /**
+   * The loop's index param name, when present — see
+   * `collectLoopChildBindings`'s doc comment (Copilot review on #2595).
+   */
+  loopIndex?: string | null,
 ): LoopChildConditional[] {
   const conditionals: LoopChildConditional[] = []
+  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex)
 
   // Widen the source-level "references loop param" check so destructured
   // callbacks fire too — the pattern text `[, cfg]` never word-matches on
@@ -1402,10 +1428,23 @@ export function collectLoopChildConditionals(
       // Pre-gate using AST `reactive` flag on the source condition before
       // paying for constant expansion — matches the legacy short-circuit.
       if (!n.reactive && !refsLoopParamInSource) return
-      const expanded = expandConstantForReactivity(n.condition, ctx, sourceFreeIds)
+      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 }]
@@ -1421,9 +1460,10 @@ export function collectLoopChildConditionals(
         condition: expanded.expr,
         whenTrueHtml,
         whenFalseHtml,
-        whenTrue: summarizeLoopChildBranch(n.whenTrue, ctx, siblingOffsets, loopParam, loopParamBindings),
-        whenFalse: summarizeLoopChildBranch(n.whenFalse, ctx, siblingOffsets, loopParam, loopParamBindings),
+        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 }),
       })
     },
   })
@@ -1444,19 +1484,23 @@ function summarizeLoopChildBranch(
   siblingOffsets: Map<IRLoop, IRNode[]>,
   loopParam?: string,
   loopParamBindings?: readonly import('../types.ts').LoopParamBinding[],
+  /** Enclosing loop's preamble locals (#2447) — see `collectLoopChildConditionals`. */
+  preambleNames?: ReadonlySet<string>,
+  /** Enclosing loop's index param name — see `collectLoopChildConditionals` (Copilot review on #2595). */
+  loopIndex?: string | null,
 ): LoopChildBranchSummary {
   const inner = collectInnerLoops([node], siblingOffsets, loopParam, ctx, branchInnerLoopOptions)
   return {
     childComponents: collectConditionalBranchChildComponents(node),
     innerLoops: inner.length > 0 ? inner : undefined,
-    conditionals: collectLoopChildConditionals(node, ctx, siblingOffsets, loopParam, loopParamBindings),
+    conditionals: collectLoopChildConditionals(node, ctx, siblingOffsets, loopParam, loopParamBindings, preambleNames, loopIndex),
     events: collectConditionalBranchEvents(node),
     // Loop-param-aware — reuses the flat loop-item collectors scoped to just
     // this branch's subtree. Both already stop descending into any further
     // nested reactive conditional (own insert()/arm), so calling them here
     // on the branch root yields exactly this branch's direct bindings
     // without re-collecting what a nested arm already owns (#2347).
-    reactiveAttrs: collectLoopChildReactiveAttrs(node, ctx, loopParam, loopParamBindings, true),
+    reactiveAttrs: collectLoopChildReactiveAttrs(node, ctx, loopParam, loopParamBindings, true, preambleNames, loopIndex),
     // Skip ONLY when the branch's entire content is a single bare
     // `expression` (no wrapping element) that MAY yield a live DOM node —
     // i.e. it contains a call anywhere (`node.hasFunctionCalls`, computed
@@ -1506,6 +1550,6 @@ function summarizeLoopChildBranch(
     // two can't disagree on shape).
     reactiveTexts: node.type === 'expression' && node.hasFunctionCalls
       ? []
-      : collectLoopChildReactiveTexts(node, ctx, loopParam, loopParamBindings, true),
+      : collectLoopChildReactiveTexts(node, ctx, loopParam, loopParamBindings, true, preambleNames, loopIndex),
   }
 }

package/src/ir-to-client-js/control-flow/plan/build-event-delegation.ts

@@ -11,6 +11,7 @@
 
 import type { TopLevelLoop, BranchLoop, LoopChildEvent } from '../../types.ts'
 import { buildChainedArrayExpr, varSlotId, substituteLoopBindings } from '../../utils.ts'
+import { identifierPattern } from '../../../identifier-pattern.ts'
 import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
   EventDelegationPlan,
@@ -138,7 +139,7 @@ function buildKeyedOrIndexLookup(args: {
     // we substitute bindings with `item.<path>` directly (#951).
     const keyWithItem = hasBindings
       ? substituteLoopBindings(args.key, args.paramBindings!, 'item')
-      : args.key.replace(new RegExp(`\\b${args.param}\\b`, 'g'), 'item')
+      : args.key.replace(identifierPattern(args.param, 'g'), 'item')
     return {
       kind: 'keyed',
       arrayExpr: args.array,

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/event-delegation.ts

@@ -34,6 +34,7 @@
 
 import { toDomEventName, varSlotId, substituteLoopBindings, buildLoopChildIndexSubtraction, DATA_KEY, keyAttrName } from '../../utils.ts'
 import { extractFreeIdentifiersFromText } from '../../csr-substitute.ts'
+import { identifierPattern } from '../../../identifier-pattern.ts'
 import type {
   EventDelegationPlan,
   KeyedItemLookup,
@@ -215,7 +216,7 @@ function emitKeyedLookup(
     const rawKey = nested.key ?? ''
     const innerKeyExpr = nested.paramBindings && nested.paramBindings.length > 0
       ? substituteLoopBindings(rawKey, nested.paramBindings, 'item')
-      : rawKey.replace(new RegExp(`\\b${nested.param}\\b`, 'g'), 'item')
+      : rawKey.replace(identifierPattern(nested.param, 'g'), 'item')
     const outerRef = hasBindings ? '__bfLoopItem' : param
     ls.push(`      const ${nested.param} = ${outerRef} && ${nested.array}.find(item => String(${innerKeyExpr}) === innerKey${nested.depth})`)
   }

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/csr-substitute.ts

@@ -28,6 +28,7 @@ import ts from 'typescript'
 import { PROPS_PARAM, inferDefaultValue } from './utils.ts'
 import { extractFreeIdentifiersFromNode } from '../analyzer.ts'
 import type { MemoInfo, SignalInfo } from '../types.ts'
+import type { BindingScope } from '../scope/binding-scope.ts'
 
 /**
  * CSR-substituted const value: the const's initializer with every
@@ -94,10 +95,21 @@ export interface CsrEnv {
  * so chained inline expansions (const A inlines to a form that mentions
  * const B's already-rewritten value) stay accurate without analytical
  * bookkeeping.
+ *
+ * `enclosingScope` (#2482 Stage 1b): an optional `BindingScope` for loop
+ * bindings ENCLOSING this expression — names bound outside the
+ * expression's own AST, which the internal `boundStack` (built purely
+ * from arrow/function scopes found while walking `value` itself) can
+ * never see on its own. Every current call site already pre-filters
+ * `env.substitutions` for loop-shadowed names before calling in (see
+ * `html-template.ts`'s `loop` case), so this is defense-in-depth, not a
+ * currently-observable behavior change: the two mechanisms should agree
+ * on what's shadowed regardless of which one runs first.
  */
 export function csrSubstitute(
   value: string,
   env: CsrEnv,
+  enclosingScope?: BindingScope,
 ): { rewritten: string; freeIdentifiers: ReadonlySet<string> } {
   if (!value || value.trim().length === 0) {
     return { rewritten: value, freeIdentifiers: new Set() }
@@ -111,7 +123,7 @@ export function csrSubstitute(
   let current = value
   let lastFreeIdentifiers: ReadonlySet<string> = new Set()
   for (let i = 0; i < maxIter; i++) {
-    const step = csrSubstituteOnce(current, env)
+    const step = csrSubstituteOnce(current, env, enclosingScope)
     lastFreeIdentifiers = step.freeIdentifiers
     if (step.rewritten === current) break
     current = step.rewritten
@@ -122,6 +134,7 @@ export function csrSubstitute(
 function csrSubstituteOnce(
   value: string,
   env: CsrEnv,
+  enclosingScope?: BindingScope,
 ): { rewritten: string; freeIdentifiers: ReadonlySet<string> } {
   if (!value || value.trim().length === 0) {
     return { rewritten: value, freeIdentifiers: new Set() }
@@ -151,12 +164,16 @@ function csrSubstituteOnce(
 
   // Track the bound names in nested arrow/function scopes so we don't
   // substitute identifiers shadowed by a parameter or local binding.
+  // `enclosingScope` seeds the OUTER frames — loop bindings introduced
+  // outside `value`'s own AST (item / index / destructure / preamble) —
+  // so a name bound there is treated identically to one bound by an
+  // arrow/function found while walking `value` itself.
   const boundStack: Array<Set<string>> = []
   const isBound = (name: string): boolean => {
     for (let i = boundStack.length - 1; i >= 0; i--) {
       if (boundStack[i].has(name)) return true
     }
-    return false
+    return enclosingScope?.isBound(name) ?? false
   }
 
   const recordSubstitution = (start: number, end: number, sub: CsrSubstitution): void => {

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

@@ -13,6 +13,7 @@ import type { ClientJsContext } from './types.ts'
 import { BF_PARENT_SCOPE_PLACEHOLDER, BF_SCOPE, escapeHtml } from '@barefootjs/shared'
 import { buildLoopChainExpr } from '../loop-chain.ts'
 import { derivesScopeFromSlot } from '../adapters/child-scope.ts'
+import { BindingScope } from '../scope/binding-scope.ts'
 
 /**
  * Protect string literals from regex-based replacements.
@@ -728,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)
@@ -1572,19 +1578,26 @@ export interface TemplateOptions {
   csrEnv?: CsrEnv
   loopDepth?: number
   /**
-   * Names bound by the ENCLOSING loops' callback params (item / index /
-   * destructured binding names), accumulated by the `loop` case as the
-   * recursion descends (#2222). Inside a loop body, `csrSubstitute`
-   * receives each expression in isolation — no enclosing arrow text — so
-   * its own bound-name tracking can't see the loop binding; the `loop`
-   * case instead filters these names out of the child recursion's
-   * `csrEnv`, so an inlinable const / signal / memo whose name is
-   * shadowed by a loop param never substitutes at the shadowed
-   * occurrence. Scope-accurate per nesting level (the CURRENT level's
-   * own `transformExpr` — e.g. the loop's array-source expression —
-   * keeps the unfiltered env).
+   * `BindingScope` for the ENCLOSING loops' callback bindings (item /
+   * index / destructured names / preamble locals), threaded through the
+   * recursion one `enterLoopRow` per nesting level (#2482 Stage 1b —
+   * migrated from the ad-hoc flat loop-bound-names `ReadonlySet<string>`
+   * this field replaces). Inside a loop body, `csrSubstitute` receives each
+   * expression in isolation — no enclosing arrow text — so its own
+   * bound-name tracking can't see the loop binding; the `loop` case
+   * instead filters these names out of the child recursion's `csrEnv`
+   * (via `scope.boundNames()`, the SHADOW-GUARD query — see
+   * `BindingScope.valueBoundNames`'s doc comment for why this must stay
+   * the all-sources query, not the value-only one), so an inlinable
+   * const / signal / memo whose name is shadowed by a loop-row binding —
+   * including a `.map()` callback preamble local (#2447) — never
+   * substitutes at the shadowed occurrence. Scope-accurate per nesting
+   * level (the CURRENT level's own `transformExpr` — e.g. the loop's
+   * array-source expression — keeps the unfiltered env). `undefined` at
+   * the top of the recursion means "no enclosing loop" (treated as
+   * `BindingScope.EMPTY`).
    */
-  loopBoundNames?: ReadonlySet<string>
+  scope?: BindingScope
   /** Emit `bf-s` placeholder on scoped elements inside a jsx-children prop (#1320). */
   inHoistedChildren?: boolean
   /**
@@ -2226,7 +2239,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
     // the IR — emit does no string transformation of its own (#1277).
     const source = templateExpr ?? expr
     if (!source) return source
-    const { rewritten, freeIdentifiers } = csrSubstitute(source, env)
+    const { rewritten, freeIdentifiers } = csrSubstitute(source, env, opts.scope)
 
     // The CSR template runs at module scope, so any post-substitution
     // free identifier that lands in `unsafeLocalNames` (init-body-only
@@ -2458,23 +2471,21 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
     }
 
     case 'loop': {
-      // Accumulate this loop's callback-bound names and filter them out
-      // of the child recursion's substitution env (#2222): an inlinable
-      // const / signal / memo whose name the callback shadows must never
-      // substitute inside the body. Destructured callbacks contribute
-      // their individual binding names; a raw pattern-text `param` (the
-      // BF025 fallback shapes, detected by the same leading-`[`/`{` check
-      // `destructureLoopParam` uses — NOT an ASCII-identifier regex, which
-      // would drop Unicode param names like `π` and re-enable the shadow
-      // bug for that body) contributes nothing — conservatively
-      // unfiltered rather than mis-filtered.
-      const boundHere = new Set(opts.loopBoundNames ?? [])
-      if (node.paramBindings && node.paramBindings.length > 0) {
-        for (const b of node.paramBindings) boundHere.add(b.name)
-      } else if (!node.param.startsWith('[') && !node.param.startsWith('{')) {
-        boundHere.add(node.param)
-      }
-      if (node.index) boundHere.add(node.index)
+      // Enter this loop's row frame and filter its bound names out of the
+      // child recursion's substitution env (#2222, #2482 Stage 1b): an
+      // inlinable const / signal / memo whose name the callback shadows —
+      // item, index, a destructured binding, OR a `.map()` callback
+      // preamble local (#2447) — must never substitute inside the body.
+      // `enterLoopRow` mirrors `jsx-to-ir.ts`'s legacy mutable loop-param
+      // set semantics exactly (see its doc comment): a raw pattern-text `param` (the
+      // BF025 fallback shapes) with no `paramBindings` still gets added,
+      // but as non-identifier pattern text it can never collide with a
+      // real const/signal/memo name, so it's a harmless no-op for this
+      // filter. `boundNames()` (not `valueBoundNames()`) is the correct
+      // query here — this is a SHADOW GUARD (every binding source must
+      // hide an outer same-named const), not a reactivity classifier.
+      const childScope = (opts.scope ?? BindingScope.EMPTY).enterLoopRow(node)
+      const boundHere = childScope.boundNames()
       const childEnv: CsrEnv = {
         ...env,
         substitutions: new Map([...env.substitutions].filter(([name]) => !boundHere.has(name))),
@@ -2483,7 +2494,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         ...opts,
         loopDepth: loopDepth + 1,
         inHoistedChildren: false,
-        loopBoundNames: boundHere,
+        scope: childScope,
         csrEnv: childEnv,
       })
       let childTemplate = node.children.map(recurseInLoopBody).join('')

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

@@ -5,6 +5,7 @@
 import type { ComponentIR, IRNode } from '../types.ts'
 import { isClientBuiltinName } from '../builtins.ts'
 import { collectValueReferencedNames } from '../value-references.ts'
+import { identifierCallPattern } from '../identifier-pattern.ts'
 
 // All exports from @barefootjs/client/runtime that may be used in generated code
 export const RUNTIME_IMPORT_CANDIDATES = [
@@ -57,7 +58,7 @@ export function detectUsedImports(code: string): Set<string> {
   const used = new Set<string>()
   for (const name of RUNTIME_IMPORT_CANDIDATES) {
     // Match function calls: name(
-    if (new RegExp(`\\b${name}\\s*\\(`).test(code)) {
+    if (identifierCallPattern(name).test(code)) {
       used.add(name)
     }
   }

package/src/ir-to-client-js/prop-handling.ts

@@ -4,6 +4,7 @@
 
 import type { ParamInfo, SignalInfo } from '../types.ts'
 import type { ClientJsContext } from './types.ts'
+import type { BindingScope } from '../scope/binding-scope.ts'
 
 /**
  * Expand dynamic prop value by resolving local constants.
@@ -11,9 +12,22 @@ import type { ClientJsContext } from './types.ts'
  * Per spec/compiler.md, no prop reference transformation is needed:
  * - Destructured props are captured once at hydration, used as-is
  * - Props object already uses props.xxx syntax
+ *
+ * `scope` (#2482 Stage 1b): the enclosing loop row's `BindingScope`, when
+ * `value` is being expanded from inside a `.map()` row. `ClientJsContext`
+ * itself carries no loop-scope field — it's a per-component object, built
+ * once and shared across the whole tree — so without this guard a loop
+ * row binding (item / index / destructured / preamble local) that shares
+ * a name with a component/module-level const resolves to the OUTER
+ * const's value instead of staying an unresolved reference to the row's
+ * own binding. `isBound` (not `valueBoundNames`) is the correct query —
+ * this is a SHADOW GUARD (every binding source hides an outer same-named
+ * const), not a reactivity classifier — see `BindingScope.valueBoundNames`'s
+ * doc comment.
  */
-export function expandDynamicPropValue(value: string, ctx: ClientJsContext): string {
+export function expandDynamicPropValue(value: string, ctx: ClientJsContext, scope?: BindingScope): string {
   const trimmedValue = value.trim()
+  if (scope?.isBound(trimmedValue)) return value
 
   const constant = ctx.localConstants.find((c) => c.name === trimmedValue)
   if (constant && constant.value) {
@@ -35,16 +49,29 @@ export function expandDynamicPropValue(value: string, ctx: ClientJsContext): str
  * Otherwise it is `originalFreeIds` passed by the caller (typically derived
  * from the IR node's `origin.freeRefs`) — `undefined` when the caller has
  * no precomputed set.
+ *
+ * `scope` (#2482 Stage 1b): see `expandDynamicPropValue` — same guard, same
+ * reasoning. Without it, a loop row's own binding (bare identifier, e.g. a
+ * `.map()` callback preamble local or the item param itself) that shares a
+ * name with a component/module-level const gets const-folded into the
+ * OUTER value here, which then corrupts BOTH the emitted expression AND
+ * downstream reactivity classification (`classifyReactivity` sees a
+ * literal instead of a live reference and concludes "not reactive" — the
+ * observable failure mode is a reactive attribute/conditional that
+ * silently freezes at its initial value instead of updating).
  */
 export function expandConstantForReactivity(
   expr: string,
   ctx: ClientJsContext,
   originalFreeIds?: ReadonlySet<string>,
+  scope?: BindingScope,
 ): { expr: string; freeIds: ReadonlySet<string> | undefined } {
   // Stateful components use props.xxx directly — reactivity is already detected.
   if (ctx.propsObjectName) return { expr, freeIds: originalFreeIds }
 
   const trimmedValue = expr.trim()
+  if (scope?.isBound(trimmedValue)) return { expr, freeIds: originalFreeIds }
+
   const constant = ctx.localConstants.find((c) => c.name === trimmedValue)
   if (constant && constant.value) {
     return { expr: constant.value, freeIds: constant.freeIdentifiers }