@barefootjs/jsx 0.31.2 → 0.31.3

package/src/jsx-to-ir.ts

@@ -62,6 +62,7 @@ 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'
 
 // =============================================================================
 // Transform Context
@@ -102,12 +103,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 +140,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 +533,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,7 +676,7 @@ 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 => ({
@@ -791,21 +805,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 +840,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 +2191,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 => new RegExp(`\\b${p}\\b`).test(exprText))
 
   // Compute AST-derived flags. `callsReactive` recognises signal-getter / memo
   // calls even inside deeper expressions (e.g., `format(count())`); `hasCalls`
@@ -4021,8 +4051,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 +4357,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 +4494,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 +4697,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 +4785,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 +6219,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 +6243,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 +6415,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,10 +7095,15 @@ 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) {
+  const boundNames = ctx.scope.valueBoundNames()
+  if (boundNames.size === 0) return false
+  for (const p of boundNames) {
     if (new RegExp(`\\b${p}\\b`).test(expr)) return true
   }
   return false
@@ -7129,10 +7227,17 @@ 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) {
+    // 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 (new RegExp(`\\b${p}\\b`).test(valueToCheck)) return true
       }
     }

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/scope/binding-scope.ts

@@ -0,0 +1,238 @@
+/**
+ * `BindingScope`: the one shared, immutable, stack-shaped model of "names
+ * bound by a loop callback" (#2482 Stage 0). Six independent ad-hoc
+ * mechanisms across the compiler currently answer this same question —
+ * `ctx.loopParams` (a mutated `Set<string>` in `jsx-to-ir.ts`),
+ * `collectLoopBoundNames` (`adapters/loop-bound-names.ts`),
+ * `resolveStaticLoopSource`'s `isNameShadowed` callback
+ * (`static-literal.ts`), and others — each reimplementing the same
+ * item/index/destructure/preamble-local bookkeeping with its own bugs and
+ * its own blind spots. This module is the single door those mechanisms
+ * migrate onto in later stages (Stage 0 only ships the service + tests;
+ * NO call site is migrated yet).
+ *
+ * Immutability is the point, not an incidental style choice:
+ * `ctx.loopParams` is `.add`/`.delete`-mutated as `jsx-to-ir.ts` walks in
+ * and back out of nested loops, so a caller that forgets (or races) a
+ * `.delete()` — or that holds a reference to the "current" set across a
+ * push/pop it didn't expect — silently observes the WRONG scope. A
+ * restore-bug of that shape is impossible by construction here:
+ * `enterLoopRow`/`enterCallback` never mutate `this`, they return a NEW
+ * `BindingScope` whose parent is untouched, so holding an old reference
+ * always sees the scope as it was, and there is no delete step to forget.
+ *
+ * Filter/sort callback params (`.filter(x => ...)`, `.sort((a, b) => ...)`,
+ * a nested arrow) are bound as `'callback'` frames via `enterCallback` —
+ * never folded into a `'loop-row'` frame's bindings. They are a distinct
+ * scope-introduction shape (an inner function's own parameter list, not a
+ * row's item/index/destructure/preamble names) even though both end up
+ * "just names you can't resolve against component-level state."
+ */
+
+/**
+ * How a name inside a `ScopeFrame` came to be bound — the row shapes
+ * (`'item'`/`'index'`/`'destructure'`/`'preamble'`) for `'loop-row'` frames,
+ * `'param'` for `'callback'` frames. One shared type because both frame
+ * kinds carry the same binding metadata.
+ */
+export type ScopeBindingSource = 'item' | 'index' | 'destructure' | 'preamble' | 'param'
+
+export interface ScopeBinding {
+  readonly source: ScopeBindingSource
+}
+
+export interface ScopeFrame {
+  readonly kind: 'loop-row' | 'callback'
+  readonly bindings: ReadonlyMap<string, ScopeBinding>
+}
+
+/**
+ * Structural pick satisfied by BOTH `IRLoop` (`packages/jsx/src/types.ts`)
+ * and the client-JS `LoopCore` family (`packages/jsx/src/ir-to-client-js/types.ts`)
+ * without importing either — this module stays dependency-free and cannot
+ * form an import cycle with `types.ts` / `ir-to-client-js`.
+ */
+export interface LoopBindingSource {
+  readonly param: string
+  readonly index?: string | null
+  readonly paramBindings?: readonly { readonly name: string }[]
+  readonly preamble?: { readonly declaredNames: readonly string[] } | null
+}
+
+/**
+ * A stack of `ScopeFrame`s, innermost frame at index 0 of the internal
+ * array (i.e. `frames[0]` is what `enterLoopRow`/`enterCallback` most
+ * recently pushed). `lookup`'s `depth` counts from `frames[0]`, so depth 0
+ * always means "the innermost frame," independent of how many ancestor
+ * frames exist.
+ */
+export class BindingScope {
+  static readonly EMPTY: BindingScope = new BindingScope([])
+
+  private constructor(private readonly frames: readonly ScopeFrame[]) {}
+
+  /**
+   * Child scope with a new `'loop-row'` frame for one loop's per-item
+   * bindings. Parent (`this`) is not mutated; the returned scope is a
+   * NEW object with `frames = [newFrame, ...this.frames]`.
+   *
+   * Binding semantics mirror `jsx-to-ir.ts`'s `ctx.loopParams` add site
+   * EXACTLY (verified against lines ~4320-4345 and the matching delete
+   * site ~4695-4710 of `packages/jsx/src/jsx-to-ir.ts`):
+   *
+   *   - When `loop.paramBindings` is non-empty (a destructured callback
+   *     param, e.g. `.map(({ id, name }) => ...)`), each `paramBindings[i].name`
+   *     is bound with source `'destructure'` and the raw `param` text
+   *     (which for a destructured callback holds the ORIGINAL pattern
+   *     source, e.g. `"{ id, name }"`, not a usable identifier) is NOT
+   *     bound. This matches `jsx-to-ir.ts`:
+   *       `if (paramBindings) { for (const b of paramBindings) ctx.loopParams.add(b.name) }`
+   *     — the `else` branch (`ctx.loopParams.add(param)`) is skipped
+   *     entirely when `paramBindings` is present.
+   *   - Otherwise (a plain identifier param, e.g. `.map(item => ...)`),
+   *     `param` itself is bound with source `'item'`.
+   *   - `index` (the second callback param, e.g. `.map((item, i) => ...)`)
+   *     is bound with source `'index'` when non-null/non-undefined.
+   *   - Every name in `preamble.declaredNames` (a `.map()` callback's
+   *     pre-return `const`/`let`/`function` locals, #2447) is bound with
+   *     source `'preamble'`.
+   *
+   *   NOTE on a sibling mechanism this method does NOT mirror:
+   *   `adapters/loop-bound-names.ts`'s `collectLoopBoundNames` adds BOTH
+   *   `node.param` AND every `paramBindings[i].name` unconditionally
+   *   (never skipping `param` in the destructured case) — a deliberately
+   *   coarser, over-inclusive collection used only to subtract names from
+   *   a flat string-typing Set (safe to over-exclude there). This method
+   *   follows the precise `jsx-to-ir.ts` `ctx.loopParams` semantics, since
+   *   that is the mechanism actually doing scope-shadowed name RESOLUTION
+   *   (the behavior `BindingScope` replaces), not coarse exclusion.
+   */
+  enterLoopRow(loop: LoopBindingSource): BindingScope {
+    const bindings = new Map<string, ScopeBinding>()
+    if (loop.paramBindings && loop.paramBindings.length > 0) {
+      for (const b of loop.paramBindings) bindings.set(b.name, { source: 'destructure' })
+    } else {
+      bindings.set(loop.param, { source: 'item' })
+    }
+    if (loop.index != null) bindings.set(loop.index, { source: 'index' })
+    for (const name of loop.preamble?.declaredNames ?? []) bindings.set(name, { source: 'preamble' })
+
+    const frame: ScopeFrame = { kind: 'loop-row', bindings }
+    return new BindingScope([frame, ...this.frames])
+  }
+
+  /**
+   * Child scope with a new `'callback'` frame binding `params` (a filter
+   * predicate's `x`, a sort comparator's `(a, b)`, or a nested arrow's
+   * parameter list) with source `'param'`. Parent is not mutated.
+   */
+  enterCallback(params: readonly string[]): BindingScope {
+    const bindings = new Map<string, ScopeBinding>()
+    for (const name of params) bindings.set(name, { source: 'param' })
+    const frame: ScopeFrame = { kind: 'callback', bindings }
+    return new BindingScope([frame, ...this.frames])
+  }
+
+  /** Innermost-first membership check across every frame in the stack. */
+  isBound(name: string): boolean {
+    for (const frame of this.frames) {
+      if (frame.bindings.has(name)) return true
+    }
+    return false
+  }
+
+  /**
+   * Resolves `name` against the frame stack innermost-first. `depth 0`
+   * means the innermost (most recently entered) frame; `null` when `name`
+   * is not bound in any frame.
+   */
+  lookup(name: string): { readonly depth: number; readonly frame: ScopeFrame; readonly binding: ScopeBinding } | null {
+    for (let depth = 0; depth < this.frames.length; depth++) {
+      const frame = this.frames[depth]
+      const binding = frame.bindings.get(name)
+      if (binding) return { depth, frame, binding }
+    }
+    return null
+  }
+
+  /**
+   * Union of every frame's bound names (every `ScopeBindingSource`), for
+   * migration interop with legacy `Set<string>`-shaped consumers (e.g.
+   * `collectLoopBoundNames`'s return type) as later stages migrate them
+   * onto `BindingScope`.
+   *
+   * This is the SHADOW-GUARD query — see {@link valueBoundNames} for the
+   * other consumer class and why the two must not be conflated.
+   */
+  boundNames(): ReadonlySet<string> {
+    if (this.boundNamesCache) return this.boundNamesCache
+    const names = new Set<string>()
+    for (const frame of this.frames) {
+      for (const name of frame.bindings.keys()) names.add(name)
+    }
+    this.boundNamesCache = names
+    return names
+  }
+
+  // Both name queries are hot (shadow guards, slot/reactivity classifiers,
+  // binding-env memo keying) and the scope is immutable, so each computes
+  // once per instance. Callers receive the cached set as ReadonlySet —
+  // never mutate it.
+  private boundNamesCache: ReadonlySet<string> | undefined
+  private valueBoundNamesCache: ReadonlySet<string> | undefined
+
+  /**
+   * Union of names bound via `'item'`/`'index'`/`'destructure'` sources
+   * only — the loop row's own per-item identity — excluding `'preamble'`
+   * (a `.map()` callback's pre-return `const`/`let`/`function` locals,
+   * #2447) and `'param'` (an `enterCallback` frame's filter/sort/nested-
+   * arrow parameters).
+   *
+   * `BindingScope` has exactly two consumer classes, and conflating them
+   * is the #2482 Stage 1a Commit 2 regression this split exists to
+   * prevent (a `ctx.scope`-wide preamble merge flipped `tag-cloud` and
+   * `preamble-cells` conformance fixtures before this method existed):
+   *
+   *   - SHADOW GUARDS (`tryResolveTemplateSpanFromConst`,
+   *     `tryResolveIdentifierAsTemplateLiteral`, `rewriteBarePropRefs`
+   *     in `jsx-to-ir.ts`) ask "is this name resolved to SOMETHING in
+   *     this scope, so an outer const/prop of the same name must not be
+   *     substituted here at this transform position" — every source
+   *     qualifies, including a preamble local shadowing a module const.
+   *     These call `isBound` / `boundNames()`.
+   *   - REACTIVITY / SLOT-ID CLASSIFIERS (`referencesLoopParam`,
+   *     `hasReactiveAttributes`, and the `BindingEnvironment.loopParams`
+   *     feed built from `makeBindingEnv`, all in `jsx-to-ir.ts`) ask
+   *     "does this expression read a value that changes per row and so
+   *     needs its own patchable slot" — a preamble local already gets
+   *     ITS OWN dedicated slot/region-patch machinery
+   *     (`preambleRegions` / `markPreambleAttrSlots`, #2447), so folding
+   *     it into this classification double-counts it. Worse: widening a
+   *     text child's `reactive` flag this way is read by
+   *     `hasDynamicContent` to decide whether the loop ROW's own root
+   *     element needs a slot — an unrelated, narrower decision that must
+   *     not move just because a preamble local is now scope-visible.
+   *     These call `valueBoundNames()`.
+   */
+  valueBoundNames(): ReadonlySet<string> {
+    if (this.valueBoundNamesCache) return this.valueBoundNamesCache
+    const names = new Set<string>()
+    for (const frame of this.frames) {
+      for (const [name, binding] of frame.bindings) {
+        if (binding.source === 'item' || binding.source === 'index' || binding.source === 'destructure') {
+          names.add(name)
+        }
+      }
+    }
+    this.valueBoundNamesCache = names
+    return names
+  }
+
+  /**
+   * Drop-in for `resolveStaticLoopSource`'s `opts.isNameShadowed`
+   * (`packages/jsx/src/static-literal.ts:112-128`).
+   */
+  asShadowPredicate(): (name: string) => boolean {
+    return (name: string) => this.isBound(name)
+  }
+}

package/src/types.ts

@@ -1882,6 +1882,14 @@ export interface ConstantInfo {
   parsed?: ParsedExpr
   /** Value with TypeScript type annotations preserved, for .tsx output */
   typedValue?: string
+  /**
+   * The declaration's explicit type annotation, verbatim from source
+   * (`node.type.getText()`), when the author wrote one. Distinct from
+   * `type`, which is also populated by inference from the initializer —
+   * emitters must only print THIS field, never an inferred type, onto a
+   * declaration (#2589).
+   */
+  typeAnnotation?: string
   valueBranches?: string[]
   declarationKind: 'const' | 'let'
   isExported?: boolean