@barefootjs/jsx 0.31.2 → 0.31.4

package/src/jsx-to-ir.ts

@@ -62,6 +62,8 @@ import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
 import { reconstructAsSegments } from './strip-types.ts'
 import { templatePartsToJsExpr } from './template-parts.ts'
 import { toHTMLAttrName, decodeEntities } from '@barefootjs/shared'
+import { BindingScope } from './scope/binding-scope.ts'
+import { identifierPattern, identifierCallPattern } from './identifier-pattern.ts'
 
 // =============================================================================
 // Transform Context
@@ -102,12 +104,18 @@ interface TransformContext {
    * `_p.<local>` (#2524 CSR half: `_p` is always caller-keyed).
    */
   _destructuredPropAliases?: Map<string, string> | null
-  /** Active loop parameter names for slotId assignment to loop-param-dependent expressions */
-  loopParams: Set<string>
+  /**
+   * The active `.map()`/callback binding stack (#2482 Stage 1a) — replaces
+   * the former mutable per-name `Set<string>` mutated in lockstep with
+   * `transformMapCall` entry/exit. `enterLoopRow`/`enterCallback` return a
+   * NEW `BindingScope`; restoring the saved parent reference on exit is
+   * the whole mechanism (no `.delete()` bookkeeping to get wrong).
+   */
+  scope: BindingScope
   /**
    * Count of enclosing `.map()` loops (0 = outermost), incremented/
    * decremented in lockstep with entering/leaving `transformMapCall`.
-   * Unlike `loopParams` (a name Set that can gain several entries for
+   * Unlike `scope` (a binding stack that can gain several bound names for
    * ONE loop level via destructuring), this is a plain per-level
    * counter — the single source of truth `IRLoop.depth` is stamped
    * from, so every adapter's `data-key`/`data-key-N` suffix derives
@@ -133,8 +141,9 @@ interface TransformContext {
   /**
    * Memoized free-refs binding environment. Built lazily by
    * `makeBindingEnv` and reused across every `resolveFreeRefs` call as
-   * long as `loopParams` content is unchanged. Invalidated by serializing
-   * `loopParams` into `_bindingEnvLoopKey` and comparing on read.
+   * long as `scope`'s bound VALUE names are unchanged. Invalidated by
+   * serializing `scope.valueBoundNames()` into `_bindingEnvLoopKey` and
+   * comparing on read.
    */
   _bindingEnv?: BindingEnvironment
   _bindingEnvLoopKey?: string
@@ -525,15 +534,21 @@ function rewriteBarePropRefs(text: string, expr: ts.Node, ctx: TransformContext)
   let propNames = getDestructuredPropNames(ctx)
   if (!propNames) return dateLowered === text ? undefined : dateLowered
   // #2222: a name bound as an enclosing loop callback's item/index param
-  // refers to the loop binding, not the prop, at THIS transform position —
-  // `ctx.loopParams` is the live loop-param set (destructured binding
-  // names and the index included), maintained by `transformMapCall` as it
-  // enters/leaves each callback, so this guard is scope-accurate rather
-  // than the coarse whole-component exclusion the SSR adapters use
-  // (#2221). Filter into a fresh set — `getDestructuredPropNames` caches
-  // its set on ctx and must not be mutated.
-  if (ctx.loopParams.size > 0) {
-    const filtered = new Set([...propNames].filter(n => !ctx.loopParams.has(n)))
+  // (or, during the return-expression transform window, a preamble-
+  // declared local — #2482 Stage 1a Commit 2 re-enters `ctx.scope` with
+  // the preamble for that window) refers to the loop binding, not the
+  // prop, at THIS transform position — maintained by `transformMapCall`
+  // as it enters/leaves each callback, so this guard is scope-accurate
+  // rather than the coarse whole-component exclusion the SSR adapters use
+  // (#2221). This is a SHADOW-GUARD query — every `ScopeBindingSource`
+  // qualifies, so it reads all-sources `boundNames()`, not
+  // `valueBoundNames()` (see that method's doc comment on
+  // `BindingScope` for the two-consumer-classes split). Filter into a
+  // fresh set — `getDestructuredPropNames` caches its set on ctx and must
+  // not be mutated.
+  const shadowingNames = ctx.scope.boundNames()
+  if (shadowingNames.size > 0) {
+    const filtered = new Set([...propNames].filter(n => !shadowingNames.has(n)))
     if (filtered.size === 0) return dateLowered === text ? undefined : dateLowered
     propNames = filtered
   }
@@ -662,24 +677,24 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
     spreadIdCounter: 0,
     isRoot: true,
     insideComponentChildren: false,
-    loopParams: new Set(),
+    scope: BindingScope.EMPTY,
     loopDepth: 0,
     patterns: {
       signals: analyzer.signals.map(s => ({
         getter: s.getter,
-        pattern: new RegExp(`\\b${s.getter}\\s*\\(`),
+        pattern: identifierCallPattern(s.getter),
       })),
       memos: analyzer.memos.map(m => ({
         name: m.name,
-        pattern: new RegExp(`\\b${m.name}\\s*\\(`),
+        pattern: identifierCallPattern(m.name),
       })),
       props: analyzer.propsParams
         .filter(p => p.name !== 'children')
-        .map(p => ({ name: p.name, pattern: new RegExp(`\\b${p.name}\\b`) })),
+        .map(p => ({ name: p.name, pattern: identifierPattern(p.name) })),
       constants: analyzer.localConstants.map(c => ({
         name: c.name,
         value: c.value,
-        pattern: new RegExp(`\\b${c.name}\\b`),
+        pattern: identifierPattern(c.name),
       })),
     },
     getJS(node: ts.Node): string {
@@ -791,21 +806,27 @@ function generateSpreadSlotId(ctx: TransformContext): string {
 /**
  * Build the binding environment for `resolveFreeRefs` from the current
  * transform context. The analyzer's collected bindings (signals, memos,
- * props, locals, imports) plus the active loop params form the resolution
- * frame; the TypeChecker, when available, is forwarded so library getters
- * carrying the Reactive<T> brand are recognised.
+ * props, locals, imports) plus the active loop-bound VALUE names (item/
+ * index/destructure — see `BindingScope.valueBoundNames`'s doc comment
+ * for why preamble locals are excluded here, #2482 Stage 1a Commit 2)
+ * form the resolution frame; the TypeChecker, when available, is
+ * forwarded so library getters carrying the Reactive<T> brand are
+ * recognised.
  *
  * Memoized on `ctx`: the returned env is identity-stable as long as
- * `loopParams` content is unchanged, which keeps the `WeakMap`-keyed
- * binding-table cache in `free-refs.ts` warm across every expression in
- * the same loop scope. `loopParams` is `.add`/`.delete`-mutated as the
- * visitor enters / leaves `.map()` callbacks, so we serialize its
- * contents into a key rather than relying on Set identity.
+ * `ctx.scope`'s bound VALUE names are unchanged, which keeps the
+ * `WeakMap`-keyed binding-table cache in `free-refs.ts` warm across every
+ * expression in the same loop scope. `ctx.scope` is REASSIGNED (never
+ * mutated) as the visitor enters / leaves `.map()` callbacks (#2482 Stage
+ * 1a), so we serialize its bound names into a key rather than relying on
+ * object identity — a sibling loop at the same nesting level would
+ * otherwise get a spurious cache miss/hit mismatch across restores.
  */
 function makeBindingEnv(ctx: TransformContext): BindingEnvironment {
-  const loopKey = ctx.loopParams.size === 0
+  const boundNames = ctx.scope.valueBoundNames()
+  const loopKey = boundNames.size === 0
     ? ''
-    : Array.from(ctx.loopParams).sort().join('\0')
+    : Array.from(boundNames).sort().join('\0')
   if (ctx._bindingEnv && ctx._bindingEnvLoopKey === loopKey) {
     return ctx._bindingEnv
   }
@@ -820,9 +841,11 @@ function makeBindingEnv(ctx: TransformContext): BindingEnvironment {
     localFunctions: a.localFunctions,
     imports: a.imports,
     ambientGlobals: a.ambientGlobals,
-    // Snapshot — the env must observe a stable view even if `ctx.loopParams`
-    // is later mutated by an enclosing visitor frame.
-    loopParams: new Set(ctx.loopParams),
+    // `valueBoundNames()` returns a per-instance set that is never
+    // mutated (cached on the immutable `BindingScope`) — a stable
+    // snapshot even if `ctx.scope` is later reassigned by an enclosing
+    // visitor frame, which swaps the instance rather than mutating it.
+    loopParams: boundNames,
     checker: a.checker,
   }
   ctx._bindingEnv = env
@@ -2169,9 +2192,17 @@ function transformExpressionInner(
   const reactive = isReactiveExpression(exprText, ctx, expr) || isReactiveOrigin(origin)
   // @client expressions always need slotId and are treated as reactive for client-side evaluation
   // Expressions inside loops that reference the loop parameter need slotId
-  // so fine-grained effects can target them for per-item signal updates
-  const refsLoopParam = ctx.loopParams.size > 0
-    && Array.from(ctx.loopParams).some(p => new RegExp(`\\b${p}\\b`).test(exprText))
+  // so fine-grained effects can target them for per-item signal updates.
+  // REACTIVITY/slotId classifier — value bindings only (item/index/
+  // destructure), NOT preamble locals: those already get their own
+  // dedicated slot/region-patch machinery (#2447), so folding them in
+  // here would double-allocate and (via `hasDynamicContent` reading this
+  // same `reactive`-adjacent signal) move an unrelated row-root slotId
+  // decision — see `BindingScope.valueBoundNames`'s doc comment
+  // (#2482 Stage 1a Commit 2).
+  const scopeValueNames = ctx.scope.valueBoundNames()
+  const refsLoopParam = scopeValueNames.size > 0
+    && Array.from(scopeValueNames).some(p => identifierPattern(p).test(exprText))
 
   // Compute AST-derived flags. `callsReactive` recognises signal-getter / memo
   // calls even inside deeper expressions (e.g., `format(count())`); `hasCalls`
@@ -2237,7 +2268,11 @@ function transformJsxFunctionCall(
   const substitutedGetJS = (node: ts.Node) => {
     let text = baseGetJS(node)
     for (const [paramName, argExpr] of substitutions) {
-      text = text.replace(new RegExp(`\\b${paramName}\\b`, 'g'), argExpr)
+      // Replacer function, not the string form: `argExpr` is arbitrary
+      // caller-supplied JS text and may itself contain `$` sequences
+      // (`$&`, `$1`, …) that `String.replace`'s string-replacement form
+      // would interpret specially instead of inserting literally (#2592).
+      text = text.replace(identifierPattern(paramName, 'g'), () => argExpr)
     }
     return text
   }
@@ -2289,7 +2324,11 @@ function transformMultiReturnJsxFunctionCall(
   const substitutedGetJS = (node: ts.Node) => {
     let text = baseGetJS(node)
     for (const [paramName, argExpr] of substitutions) {
-      text = text.replace(new RegExp(`\\b${paramName}\\b`, 'g'), argExpr)
+      // Replacer function, not the string form: `argExpr` is arbitrary
+      // caller-supplied JS text and may itself contain `$` sequences
+      // (`$&`, `$1`, …) that `String.replace`'s string-replacement form
+      // would interpret specially instead of inserting literally (#2592).
+      text = text.replace(identifierPattern(paramName, 'g'), () => argExpr)
     }
     return text
   }
@@ -4021,8 +4060,13 @@ function transformMapCall(
   method: 'map' | 'flatMap' = 'map'
 ): IRLoop | null {
   // Capture nesting depth before we register this map's own params.
-  // ctx.loopParams is populated by the *outer* map; if non-empty we are inside one.
-  const isNested = ctx.loopParams.size > 0
+  // ctx.scope is populated by the *outer* map; if any VALUE names (item/
+  // index/destructure) are bound we are inside one. Reads
+  // `valueBoundNames()`, not `boundNames()`, for consistency with the
+  // other structural/reactivity consumers (#2482 Stage 1a Commit 2) —
+  // though a bound outer-loop row always carries at least one value
+  // binding regardless, so this can't actually change the answer.
+  const isNested = ctx.scope.valueBoundNames().size > 0
   // Diagnostic count at entry — the structural net at the scalar fallthrough
   // de-dups against refusals fired DURING this call (leaf-wiring, DSL gates),
   // never against unrelated diagnostics recorded before it.
@@ -4322,17 +4366,17 @@ function transformMapCall(
       }
     }
 
-    // Register loop params so expressions referencing them get slotId.
-    // For destructured patterns, register the individual binding names —
-    // `\b${param}\b` never matches a bare name like `cfg` when `param` is
-    // `[, cfg]`, which would otherwise leave reactive-expression detection
-    // silently broken for destructured callbacks.
-    if (paramBindings) {
-      for (const b of paramBindings) ctx.loopParams.add(b.name)
-    } else {
-      ctx.loopParams.add(param)
-    }
-    if (index) ctx.loopParams.add(index)
+    // Register loop-bound names so expressions referencing them get slotId,
+    // by entering a new BindingScope frame for this row (#2482 Stage 1a).
+    // For destructured patterns, the frame binds the individual binding
+    // names — `\b${param}\b` never matches a bare name like `cfg` when
+    // `param` is `[, cfg]`, which would otherwise leave reactive-expression
+    // detection silently broken for destructured callbacks.
+    // `savedScope` is restored (not deleted-from) at the matching exit site
+    // below, so a nested loop reusing a param name can never corrupt the
+    // outer scope.
+    const savedScope = ctx.scope
+    ctx.scope = ctx.scope.enterLoopRow({ param, index, paramBindings })
     ctx.loopDepth++
 
     // Logical control flow (`cond && <X/>`, `a ?? themeLogo()`) as the map
@@ -4459,6 +4503,51 @@ function transformMapCall(
             (s): s is ts.ReturnStatement => ts.isReturnStatement(s) && s.expression != null
           )
         : undefined
+
+      // #2482 Stage 1a Commit 2 — ordering note: the STRUCTURED preamble
+      // (`MapCallbackPreamble`, built further down by
+      // `preambleFromValueStatements` / `buildPreambleSegments`, whichever
+      // branch below the return-expression shape takes) isn't known until
+      // well AFTER this point. But `transformNode(returnExpr, ctx)` just
+      // below walks the return expression's own child expressions RIGHT
+      // NOW — before that happens — so a preamble-declared local shadowing
+      // an outer const/prop must already be bound in `ctx.scope`, or
+      // `tryResolveTemplateSpanFromConst` / `tryResolveIdentifierAsTemplateLiteral`
+      // / `rewriteBarePropRefs` bake the OUTER value into every row instead
+      // of leaving the row-local unresolved (#2222-family, the const/prop-
+      // shadow bug class). Fix: a lightweight declared-names-only pre-scan
+      // — the exact same "statements before the return" shape
+      // `preambleFromValueStatements`/`buildPreambleSegments` scan below —
+      // re-enters the row's `BindingScope` frame (off `savedScope`, the
+      // pre-loop parent, so this REPLACES the param/index-only frame
+      // rather than stacking a second one) with the preamble included, for
+      // the duration of the return-expression transform. Restored back to
+      // the preamble-less row scope right after that window closes (see
+      // `rowScopeBeforePreamble` below) — everything past this window
+      // (the flatMap fallbacks, and the whole rest of `transformMapCall`
+      // after this `if (ts.isBlock(body))` branch) must keep observing
+      // EXACTLY the old (Commit 1) membership, since slotId-allocation
+      // classifiers there read `ctx.scope.valueBoundNames()`, which never
+      // included preamble names to begin with — only shadow guards need
+      // the widened view, and only for this window.
+      let rowScopeBeforePreamble: BindingScope | null = null
+      if (returnStmt) {
+        const preambleNames = new Set<string>()
+        for (const stmt of body.statements) {
+          if (stmt === returnStmt) break
+          collectPreambleDeclaredNames(stmt, preambleNames)
+        }
+        if (preambleNames.size > 0) {
+          rowScopeBeforePreamble = ctx.scope
+          ctx.scope = savedScope.enterLoopRow({
+            param,
+            index,
+            paramBindings,
+            preamble: { declaredNames: [...preambleNames] },
+          })
+        }
+      }
+
       if (returnStmt && returnStmt.expression) {
         let returnExpr = returnStmt.expression
         while (ts.isParenthesizedExpression(returnExpr)) {
@@ -4617,6 +4706,14 @@ function transformMapCall(
         }
       }
 
+      // Window closed — restore the preamble-less row scope so every
+      // consumer past this point (the flatMap fallbacks immediately
+      // below, and the rest of `transformMapCall` after this branch)
+      // keeps observing EXACTLY the pre-rework membership.
+      if (rowScopeBeforePreamble) {
+        ctx.scope = rowScopeBeforePreamble
+      }
+
       // flatMap block body fallback: compile JSX inline when children
       // couldn't be extracted via the standard single-return path. A pure
       // single-`return <call>` projection is NOT taken here — it lowers to
@@ -4697,13 +4794,10 @@ function transformMapCall(
       )
     }
 
-    // Unregister loop params
-    if (paramBindings) {
-      for (const b of paramBindings) ctx.loopParams.delete(b.name)
-    } else {
-      ctx.loopParams.delete(param)
-    }
-    if (index) ctx.loopParams.delete(index)
+    // Restore the parent scope — the BindingScope twin of the old
+    // "unregister loop params" delete block, but by reference rather than
+    // by name, so it can never miss an entry the add-site added.
+    ctx.scope = savedScope
     ctx.loopDepth--
   }
 
@@ -6134,10 +6228,14 @@ function tryResolveTemplateSpanFromConst(
   // ${IDENT}
   if (ts.isIdentifier(expr)) {
     // #2222-family: inside a loop callback the name may be the loop's
-    // item/index binding shadowing a same-named const — resolving the
-    // const would bake the outer value into every row. Fall back to
-    // the bare-expression path, which sees the loop binding.
-    if (ctx.loopParams.has(expr.text)) return null
+    // item/index/preamble binding shadowing a same-named const —
+    // resolving the const would bake the outer value into every row.
+    // Fall back to the bare-expression path, which sees the loop
+    // binding. SHADOW-GUARD query — `isBound` (all sources), not
+    // `valueBoundNames()` — see `BindingScope.valueBoundNames`'s doc
+    // comment for the two-consumer-classes split (#2482 Stage 1a
+    // Commit 2).
+    if (ctx.scope.isBound(expr.text)) return null
     const constInfo = findLocalConst(expr.text, ctx.analyzer)
     if (!constInfo) return null
     const ast = parseConstInitializer(constInfo)
@@ -6154,7 +6252,7 @@ function tryResolveTemplateSpanFromConst(
     // Same loop-shadowing guard as the ${IDENT} arm: `tone[k]` inside
     // `items.map((tone) => …)` must read the row's `tone`, not a
     // same-named module/component record const.
-    if (ctx.loopParams.has(expr.expression.text)) return null
+    if (ctx.scope.isBound(expr.expression.text)) return null
     const constInfo = findLocalConst(expr.expression.text, ctx.analyzer)
     if (!constInfo) return null
     const ast = parseConstInitializer(constInfo)
@@ -6326,9 +6424,13 @@ function tryResolveIdentifierAsTemplateLiteral(
   // outer const's literal into the IR here bakes the same hard-coded
   // value into EVERY adapter's output (e.g. `key={label}` inside
   // `.map((label) => ...)` becoming a constant duplicate key).
-  // `ctx.loopParams` is the live loop-param set (destructured binding
-  // names and index included), so the guard is scope-accurate.
-  if (ctx.loopParams.has(ident.text)) return null
+  // `ctx.scope` is the live loop-binding stack (destructured binding
+  // names and index included — plus, during the return-expression
+  // transform window, the preamble's declared names once
+  // `transformMapCall` re-enters the row scope with them, #2482 Stage 1a
+  // Commit 2), so the guard is scope-accurate. This is a SHADOW-GUARD
+  // query — reads `isBound` (all sources), not `valueBoundNames()`.
+  if (ctx.scope.isBound(ident.text)) return null
   const constInfo = findLocalConst(ident.text, ctx.analyzer)
   if (!constInfo) return null
   const ast = parseConstInitializer(constInfo)
@@ -7002,11 +7104,16 @@ function isSignalOrMemoArray(array: string, ctx: TransformContext): boolean {
  * Used by conditional transforms to assign slotId for per-item signal reactivity.
  * NOT added to isReactiveExpression to avoid promoting text expressions
  * like {item.name} to reactive (they use a separate slotId path).
+ *
+ * REACTIVITY/slotId classifier — reads `valueBoundNames()` (item/index/
+ * destructure only), NOT preamble locals; see `BindingScope.valueBoundNames`'s
+ * doc comment (#2482 Stage 1a Commit 2).
  */
 function referencesLoopParam(expr: string, ctx: TransformContext): boolean {
-  if (ctx.loopParams.size === 0) return false
-  for (const p of ctx.loopParams) {
-    if (new RegExp(`\\b${p}\\b`).test(expr)) return true
+  const boundNames = ctx.scope.valueBoundNames()
+  if (boundNames.size === 0) return false
+  for (const p of boundNames) {
+    if (identifierPattern(p).test(expr)) return true
   }
   return false
 }
@@ -7129,11 +7236,18 @@ function hasReactiveAttributes(attrs: IRAttribute[], ctx: TransformContext): boo
     if (isSignalOrMemoReference(valueToCheck, ctx) || isPropsReference(valueToCheck, ctx)) {
       return true
     }
-    // Check if attribute references any active loop parameters —
-    // loop root elements need a slotId so className can be updated reactively.
-    if (ctx.loopParams.size > 0) {
-      for (const p of ctx.loopParams) {
-        if (new RegExp(`\\b${p}\\b`).test(valueToCheck)) return true
+    // Check if attribute references any active loop-bound VALUE names —
+    // loop root elements need a slotId so className can be updated
+    // reactively. REACTIVITY/slotId classifier — value bindings only
+    // (item/index/destructure), not preamble locals; see
+    // `BindingScope.valueBoundNames`'s doc comment (#2482 Stage 1a
+    // Commit 2) — this is the exact check whose over-widening flipped
+    // the `tag-cloud`/`preamble-cells` conformance fixtures before the
+    // source-filtered query existed.
+    const scopeValueNames = ctx.scope.valueBoundNames()
+    if (scopeValueNames.size > 0) {
+      for (const p of scopeValueNames) {
+        if (identifierPattern(p).test(valueToCheck)) return true
       }
     }
   }

package/src/module-exports.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ComponentIR, ParamInfo } from './types.ts'
+import { identifierPattern } from './identifier-pattern.ts'
 
 /**
  * Emit module-level exports for local declarations and `export { ... } [from '...']`
@@ -140,7 +141,7 @@ export function findReachableNames(
   const queue: string[] = []
 
   for (const name of allNames) {
-    if (new RegExp(`\\b${name}\\b`).test(primaryRefs)) {
+    if (identifierPattern(name).test(primaryRefs)) {
       reachable.add(name)
       queue.push(name)
     }
@@ -150,7 +151,7 @@ export function findReachableNames(
     const current = queue.shift()!
     const body = bodyMap.get(current) || ''
     for (const name of allNames) {
-      if (!reachable.has(name) && new RegExp(`\\b${name}\\b`).test(body)) {
+      if (!reachable.has(name) && identifierPattern(name).test(body)) {
         reachable.add(name)
         queue.push(name)
       }

package/src/prop-rewrite.ts

@@ -14,7 +14,7 @@
  * stack, so `items.map((title) => title.a)` never turns into the
  * syntactically invalid `.map((_p.title) => _p.title.a)` when `title`
  * is also a prop. (Names bound by loop callbacks that ENCLOSE the
- * expression are the caller's job — see the `ctx.loopParams` filter in
+ * expression are the caller's job — see the `ctx.scope` filter in
  * `jsx-to-ir.ts`'s `rewriteBarePropRefs` wrapper, #2222.)
  */
 

package/src/relocate.ts

@@ -22,6 +22,7 @@ import type {
 } from './adapters/interface.ts'
 import { tsNodeToParsedExpr, type ParsedExpr } from './expression-parser.ts'
 import { prepareLoweringMatchers, type LoweringMatcher } from './lowering-registry.ts'
+import { identifierPattern } from './identifier-pattern.ts'
 
 export interface RelocateEnv {
   /**
@@ -713,7 +714,7 @@ function scanRefsByName(
 ): Map<string, ts.Identifier[]> {
   const result = new Map<string, ts.Identifier[]>()
   for (const name of bindings.keys()) {
-    const re = new RegExp(`\\b${name}\\b`)
+    const re = identifierPattern(name)
     if (re.test(text)) result.set(name, [])
   }
   return result