@barefootjs/jsx 0.31.2 → 0.31.4

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),
   )