@barefootjs/jsx 0.31.3 → 0.31.4

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

@@ -5,12 +5,13 @@
 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 } 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 { 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 +312,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 +333,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 +376,8 @@ export function collectInnerLoops(
               siblingOffsets,
               n.param,
               n.paramBindings,
+              innerPreambleNames,
+              n.index,
             ))
           }
         }
@@ -671,7 +674,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 +1149,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 +1349,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 +1364,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 +1378,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,7 +1427,7 @@ 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)
       // 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
@@ -1421,8 +1446,8 @@ 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 }),
       })
     },
@@ -1444,19 +1469,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 +1535,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/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/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.
@@ -1572,19 +1573,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 +2234,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 +2466,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 +2489,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 }

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

@@ -18,6 +18,41 @@ import { attrValueToString, freeIdsFromRefs, tokenContainsIdent } from './utils.
 import { expandConstantForReactivity } from './prop-handling.ts'
 import { extractFreeIdentifiersFromText } from './csr-substitute.ts'
 import { walkIR, stopAt } from './walker.ts'
+import { BindingScope } from '../scope/binding-scope.ts'
+import { identifierCallPattern } from '../identifier-pattern.ts'
+
+/**
+ * Build the `BindingScope` for one loop row's own bindings — item /
+ * destructured param / index names plus (when supplied) the `.map()`
+ * callback's preamble locals (#2447) — for the `expandConstantForReactivity`
+ * shadow guard (#2482 Stage 1b). `undefined` when there's no enclosing loop
+ * (`loopParam` unset), matching every caller's existing "no loop" shape.
+ *
+ * `loopIndex` (Copilot review on #2595): a `.map((item, i) => ...)`
+ * callback's second param is a real row-scoped binding exactly like
+ * `item` — an `i`-shadows-a-module-const attr/text (e.g.
+ * `data-idx={/* @client *\/ i}`) const-folds to the outer value exactly
+ * like an item-param shadow does when the index name isn't in scope.
+ * Only guarded when the CALLER passes it in, though — none of the
+ * `collectLoopChild*` collectors' own callers threaded the IR loop's
+ * `index` field through before this fix (see each call site's own
+ * `undefined`/omitted-arg default), so `undefined` here still means "not
+ * guarded," not "no index param."
+ */
+export function buildLoopRowScope(
+  loopParam?: string,
+  loopParamBindings?: readonly LoopParamBinding[],
+  preambleNames?: ReadonlySet<string>,
+  loopIndex?: string | null,
+): BindingScope | undefined {
+  if (!loopParam) return undefined
+  return BindingScope.EMPTY.enterLoopRow({
+    param: loopParam,
+    paramBindings: loopParamBindings,
+    index: loopIndex,
+    preamble: preambleNames && preambleNames.size > 0 ? { declaredNames: [...preambleNames] } : undefined,
+  })
+}
 
 /**
  * Phase 2 reactivity detection: determines if a code expression needs `createEffect`
@@ -146,13 +181,13 @@ export function needsEffectWrapper(
   freeIdentifiers?: ReadonlySet<string>,
 ): boolean {
   for (const signal of ctx.signals) {
-    if (new RegExp(`\\b${signal.getter}\\s*\\(`).test(expr)) {
+    if (identifierCallPattern(signal.getter).test(expr)) {
       return true
     }
   }
 
   for (const memo of ctx.memos) {
-    if (new RegExp(`\\b${memo.name}\\s*\\(`).test(expr)) {
+    if (identifierCallPattern(memo.name).test(expr)) {
       return true
     }
   }
@@ -555,6 +590,14 @@ function traverseForComponents(
  * Defaults to false: some callers (e.g. a plain nested `.map()`'s own
  * per-item bindings) have no sibling conditional collector, so a slotId'd
  * conditional's inlined content is only ever reachable by descending here.
+ *
+ * `preambleNames` (#2482 Stage 1b): the enclosing loop's `.map()` callback
+ * preamble locals (#2447), when known — folded into the `expandConstantForReactivity`
+ * shadow guard via `buildLoopRowScope` so a preamble local shadowing a
+ * component/module const doesn't get const-folded here.
+ *
+ * `loopIndex` (Copilot review on #2595): the loop's index param name
+ * (`.map((item, i) => ...)`'s `i`), when known — see `buildLoopRowScope`.
  */
 export function collectLoopChildReactiveTexts(
   node: IRNode,
@@ -562,8 +605,11 @@ export function collectLoopChildReactiveTexts(
   loopParam?: string,
   loopParamBindings?: readonly LoopParamBinding[],
   stopAtReactiveConditionals = false,
+  preambleNames?: ReadonlySet<string>,
+  loopIndex?: string | null,
 ): LoopChildReactiveText[] {
   const texts: LoopChildReactiveText[] = []
+  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex)
   walkIR(node, false, {
     // Skip loop/async/if-statement subtrees — the original walker omitted
     // them; they have their own scopes (inner-loop reconciliation, async
@@ -579,7 +625,7 @@ export function collectLoopChildReactiveTexts(
       // (a `joinArrayChild` region's value is raw HTML, not text).
       if (n.preambleRegion) return
       const originFreeIds = freeIdsFromRefs(n.origin?.freeRefs)
-      const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds)
+      const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds, scope)
       // Include if expression reads signals OR references the loop parameter
       // (loop param becomes a signal accessor via per-item signals). Falls
       // back to the Solid-style AST-flag wrap decision — mirroring
@@ -621,6 +667,8 @@ export function collectLoopChildReactiveTexts(
  * `stopAtReactiveConditionals` (#2347): see `collectLoopChildReactiveTexts` —
  * same semantics. Pass true only when the caller also separately collects
  * nested reactive conditionals and gives each its own `insert()`.
+ *
+ * `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). */
@@ -636,8 +684,10 @@ export function collectLoopChildReactiveAttrs(
   loopParamBindings?: readonly LoopParamBinding[],
   stopAtReactiveConditionals = false,
   preambleNames?: ReadonlySet<string>,
+  loopIndex?: string | null,
 ): LoopChildReactiveAttr[] {
   const attrs: LoopChildReactiveAttr[] = []
+  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex)
   traverseElements(node, (el) => {
     if (el.slotId) {
       for (const attr of el.attrs) {
@@ -653,7 +703,7 @@ export function collectLoopChildReactiveAttrs(
         if (attr.name === 'key') continue
         const valueStr = attrValueToString(attr.value)
         if (!valueStr) continue
-        const expanded = expandConstantForReactivity(valueStr, ctx, attr.freeIdentifiers)
+        const expanded = expandConstantForReactivity(valueStr, ctx, attr.freeIdentifiers, scope)
         // `/* @client */` always defers via per-item createEffect
         // regardless of the reactivity classifier — matches the
         // top-level `collectElements.element` and the conditional

package/src/ir-to-client-js/rewrite-props-object.ts

@@ -24,6 +24,7 @@
 
 import ts from 'typescript'
 import { PROPS_PARAM } from './utils.ts'
+import { identifierPattern } from '../identifier-pattern.ts'
 
 /**
  * Rename every value-position reference to `propsObjectName` in `code`
@@ -36,7 +37,7 @@ export function rewritePropsObjectRef(code: string, propsObjectName: string | nu
   if (srcPropsName === PROPS_PARAM) return code
 
   // Quick exit when the name doesn't appear at all.
-  if (!new RegExp(`\\b${srcPropsName}\\b`).test(code)) return code
+  if (!identifierPattern(srcPropsName).test(code)) return code
 
   const sourceFile = ts.createSourceFile(
     'init-body.ts',

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

@@ -8,6 +8,7 @@ import type { AttrValue, IRTemplatePart, LoopParamBinding, FreeReference, IRNode
 import type { TopLevelLoop, BranchLoop, LoopOffset } from './types.ts'
 import { buildLoopChainExpr } from '../loop-chain.ts'
 import { templatePartsToJsExpr } from '../template-parts.ts'
+import { escapeIdentifierForRegex, ID_BOUNDARY_BEFORE, ID_BOUNDARY_AFTER } from '../identifier-pattern.ts'
 import {
   iterateJsTokens,
   isIdentifierLikeToken,
@@ -337,10 +338,6 @@ export function inferDefaultValue(type: { kind: string; primitive?: string }): s
   return 'undefined'
 }
 
-function escapeRegExp(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
 /**
  * Flatten an `OriginInfo.freeRefs` list to a plain `Set<string>` of free
  * identifier names (#1267). Skips `kind: 'reactive-brand'` entries whose
@@ -561,8 +558,12 @@ export function wrapLoopParamAsAccessor(expr: string, paramName: string, binding
   if (bindings && bindings.length > 0) {
     return rewriteLoopBindingRefs(expr, bindings, '__bfItem()')
   }
-  const re = new RegExp(`\\b${escapeRegExp(paramName)}\\b(?!\\s*\\()(?!-)`, 'g')
-  return replaceInExprContexts(expr, re, `${paramName}()`)
+  // `paramName` is a legal JS identifier and may itself start with `$`
+  // (`$1`, `$&`, …) — a plain string replacement would risk `String.replace`
+  // reading those as backreference/whole-match sequences, so use a replacer
+  // function to insert the accessor text literally (#2592).
+  const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(paramName)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
+  return replaceInExprContexts(expr, re, () => `${paramName}()`)
 }
 
 /**
@@ -588,8 +589,8 @@ function rewriteLoopBindingRefs(
   const byName = new Map<string, LoopParamBinding>()
   for (const b of bindings) byName.set(b.name, b)
   const preprocessed = expandShorthandBindings(expr, new Set(byName.keys()))
-  const alt = bindings.map(b => escapeRegExp(b.name)).join('|')
-  const re = new RegExp(`\\b(${alt})\\b`, 'g')
+  const alt = bindings.map(b => escapeIdentifierForRegex(b.name)).join('|')
+  const re = new RegExp(`${ID_BOUNDARY_BEFORE}(${alt})${ID_BOUNDARY_AFTER}`, 'gu')
   return replaceInExprContexts(preprocessed, re, (_m: string, name: string) =>
     renderLoopBindingAccess(byName.get(name)!, accessor),
   )