@barefootjs/jsx 0.31.1 → 0.31.3

package/src/jsx-to-ir.ts

@@ -49,6 +49,7 @@ import {
   rewriteBarePropRefs as rewriteBarePropRefsCore,
   collectAstPropRefs,
 } from './prop-rewrite.ts'
+import { buildPropAliasMap } from './props-binding.ts'
 import { resolveFreeRefs, isNameBound as isNameBoundInEnv, type BindingEnvironment } from './free-refs.ts'
 import { computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { createTemplateAwareStringProtector } from './ir-to-client-js/html-template.ts'
@@ -59,7 +60,9 @@ import type { LoweringMatcher } from './lowering-registry.ts'
 import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx, extractMultiReturnJsxBranches, type MultiReturnJsxBranches } from './analyzer.ts'
 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
@@ -91,12 +94,27 @@ interface TransformContext {
   _moduleClientSignalNames?: Set<string>
   /** Cached set of destructured prop names for AST-based rewriting */
   _destructuredPropNames?: Set<string> | null
-  /** Active loop parameter names for slotId assignment to loop-param-dependent expressions */
-  loopParams: Set<string>
+  /**
+   * Cached local-name → caller-facing-key (`sourceName ?? name`) map for
+   * `_destructuredPropNames`, entries only for names that actually rename
+   * (`{ n: count }` → `count` → `n`). Built alongside `_destructuredPropNames`
+   * so both stay in lockstep with the same shadow-filtered eligible set —
+   * consumed by `rewriteBarePropRefsCore` to emit `_p.<caller>` instead of
+   * `_p.<local>` (#2524 CSR half: `_p` is always caller-keyed).
+   */
+  _destructuredPropAliases?: Map<string, string> | null
+  /**
+   * 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
@@ -122,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
@@ -514,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
   }
@@ -536,7 +561,8 @@ function rewriteBarePropRefs(text: string, expr: ts.Node, ctx: TransformContext)
   // `_branchScopePropDeps` at branch entry; here we just walk `expr`
   // for references to those locals and union the matching dep sets.
   const extraPropRefs = collectBranchLocalPropRefsViaSubstitution(expr, ctx)
-  return rewriteBarePropRefsCore(dateLowered, expr, propNames, extraPropRefs)
+  const propAliases = getDestructuredPropAliases(ctx)
+  return rewriteBarePropRefsCore(dateLowered, expr, propNames, extraPropRefs, propAliases ?? undefined)
 }
 
 /**
@@ -618,14 +644,26 @@ function getDestructuredPropNames(ctx: TransformContext): Set<string> | null {
         if (!isDestructureFromProps) shadowed.add(c.name)
       }
     }
-    const names = ctx.analyzer.propsParams
-      .map(p => p.name)
-      .filter(n => !shadowed.has(n))
+    const eligible = ctx.analyzer.propsParams.filter(p => !shadowed.has(p.name))
+    const names = eligible.map(p => p.name)
     ctx._destructuredPropNames = names.length > 0 ? new Set(names) : null
+    ctx._destructuredPropAliases = buildPropAliasMap(eligible) ?? null
   }
   return ctx._destructuredPropNames ?? null
 }
 
+/**
+ * Companion to `getDestructuredPropNames`: the local-name → caller-key
+ * alias map for the SAME shadow-filtered eligible set, populated as a
+ * side effect of that call. Always call `getDestructuredPropNames` first
+ * (or accept it may return an empty cache) — the two caches are written
+ * together in one pass.
+ */
+function getDestructuredPropAliases(ctx: TransformContext): Map<string, string> | null {
+  if (ctx._destructuredPropNames === undefined) getDestructuredPropNames(ctx)
+  return ctx._destructuredPropAliases ?? null
+}
+
 function createTransformContext(analyzer: AnalyzerContext): TransformContext {
   return {
     analyzer,
@@ -638,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 => ({
@@ -767,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
   }
@@ -796,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
@@ -1278,12 +1324,21 @@ function transformJsxElement(
  *  - `<textarea>` with no children gains a NON-reactive expression child
  *    (the initial value as element content — updates keep flowing through
  *    the `.value` effect, deliberately not a live text slot);
- *  - `<select>` distributes `selected={(value) === 'opt'}` onto each
- *    statically-valued `<option>` (incl. under `<optgroup>`/fragments) —
- *    the exact per-option comparison shape the `select-option-selected`
- *    fixture already proves across every adapter. Options rendered by a
- *    dynamic loop can't be statically distributed and are left to the
- *    hydrate-time effect (tracked with #2466 on the #2464 thread).
+ *  - `<select>` distributes `selected={(value) === optValue}` onto each
+ *    `<option>` (incl. under `<optgroup>`/fragments, and under a `.map()`
+ *    loop body) — the exact per-option comparison shape the
+ *    `select-option-selected` fixture already proves across every adapter.
+ *    A literal `optValue` (e.g. `value="banana"`) compares by
+ *    `JSON.stringify`; an expression `optValue` (a static dynamic value, or
+ *    a loop row reading its item — e.g. `value={o.id}`) compares against
+ *    the expression text directly. For a loop row this makes `selected` an
+ *    ordinary per-item reactive attribute like any other (`o.id`, the row's
+ *    text) — it rides the SAME loop-plan machinery
+ *    (`collectLoopChildReactiveAttrs` → `emitAttrUpdate`, which special-cases
+ *    `selected` as a boolean DOM PROPERTY write, not just an HTML attribute)
+ *    that already reruns per row on item change and per outer-signal change,
+ *    so selectedness is recomputed instead of staying attached to whichever
+ *    physical `<option>` a reorder happened to rewrite in place (#2466).
  */
 function lowerFormControlValueSsr(
   tagName: string,
@@ -1318,21 +1373,47 @@ function lowerFormControlValueSsr(
     return
   }
 
-  const selectedFor = (optValue: string): AttrValue =>
+  const selectedForLiteral = (optValue: string): AttrValue =>
     AttrValueOf.expression(
       `(${expr}) === ${JSON.stringify(optValue)}`,
       templateExpr !== undefined
         ? { templateExpr: `(${templateExpr}) === ${JSON.stringify(optValue)}` }
         : undefined,
     )
+  // An expression-valued `option value` — the shape every `.map()` loop row
+  // uses (`value={o.id}`) since the whole point of the loop is a per-item
+  // value. Compares the controlled value directly against the option's own
+  // value EXPRESSION TEXT (never JSON-stringified — it is JS, not a string
+  // literal). Inside a loop row this expression reads both the row item
+  // (`o.id`) and the outer controlled signal (`expr`, e.g. `val()`), which
+  // is exactly the "reads both" shape `collectLoopChildReactiveAttrs` /
+  // `classifyLazyBinding` already know how to place into both `applyItem`
+  // (row changed) and `applyOuter` (controlled value changed) — no new loop
+  // machinery, just one more per-row reactive attribute (#2466).
+  const selectedForExpr = (optExpr: string, optTemplateExpr: string | undefined): AttrValue =>
+    AttrValueOf.expression(
+      `(${expr}) === (${optExpr})`,
+      templateExpr !== undefined || optTemplateExpr !== undefined
+        ? { templateExpr: `(${templateExpr ?? expr}) === (${optTemplateExpr ?? optExpr})` }
+        : undefined,
+    )
   const distribute = (nodes: IRNode[]): void => {
     for (const n of nodes) {
       if (n.type === 'element' && n.tag === 'option') {
         if (n.attrs.some(a => a.name === 'selected')) continue
         const optValue = n.attrs.find(a => a.name === 'value')
-        if (!optValue || optValue.value.kind !== 'literal') continue
-        n.attrs.push({ name: 'selected', value: selectedFor(optValue.value.value), loc: n.loc })
-      } else if (n.type === 'fragment' || (n.type === 'element' && n.tag === 'optgroup')) {
+        if (!optValue) continue
+        if (optValue.value.kind === 'literal') {
+          n.attrs.push({ name: 'selected', value: selectedForLiteral(optValue.value.value), loc: n.loc })
+        } else if (optValue.value.kind === 'expression') {
+          const selected = selectedForExpr(optValue.value.expr, optValue.value.templateExpr)
+          n.attrs.push({ name: 'selected', value: selected, loc: n.loc })
+        }
+      } else if (
+        n.type === 'fragment' ||
+        n.type === 'loop' ||
+        (n.type === 'element' && n.tag === 'optgroup')
+      ) {
         distribute(n.children)
       }
     }
@@ -2110,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`
@@ -3962,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.
@@ -4263,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
@@ -4400,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)) {
@@ -4558,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
@@ -4638,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--
   }
 
@@ -6075,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)
@@ -6095,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)
@@ -6267,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)
@@ -6777,8 +6929,8 @@ function processComponentProps(
       // the bare `classes` identifier with no prop refs, so the rewrite
       // no-ops and the module-scope registration template leaks bare
       // destructured props into `renderChild(...)` (#2468).
-      const collapsed = templatePartsToJsString(value.parts)
-      const collapsedTemplate = templatePartsToJsString(value.parts, { useTemplate: true })
+      const collapsed = templatePartsToJsExpr(value.parts)
+      const collapsedTemplate = templatePartsToJsExpr(value.parts, { useTemplate: true })
       value = AttrValueOf.expression(collapsed, {
         parts: value.parts,
         ...(collapsedTemplate !== collapsed && { templateExpr: collapsedTemplate }),
@@ -6820,32 +6972,6 @@ function processComponentProps(
   return props
 }
 
-/**
- * Flatten a structured template-literal's parts back into a JS expression
- * string. Used at IR construction time when a structured `template` variant
- * needs to be collapsed into an `expression` for component-prop forwarding —
- * component props are runtime JS values, not HTML attribute bodies.
- */
-function templatePartsToJsString(parts: readonly IRTemplatePart[], opts?: { useTemplate?: boolean }): string {
-  let result = '`'
-  for (const part of parts) {
-    if (part.type === 'string') {
-      result += (opts?.useTemplate && part.templateValue) ? part.templateValue : part.value
-    } else if (part.type === 'ternary') {
-      const cond = (opts?.useTemplate && part.templateCondition) ? part.templateCondition : part.condition
-      result += `\${${cond} ? '${part.whenTrue}' : '${part.whenFalse}'}`
-    } else if (part.type === 'lookup') {
-      const key = (opts?.useTemplate && part.templateKey) ? part.templateKey : part.key
-      const obj = '{' + Object.entries(part.cases).map(
-        ([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`
-      ).join(', ') + '}'
-      result += `\${(${obj})[${key}]}`
-    }
-  }
-  result += '`'
-  return result
-}
-
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -6969,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
@@ -7096,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/module-exports.ts

@@ -21,10 +21,19 @@ export function generateModuleExports(
   ir: ComponentIR,
   extraInlineExported: ReadonlySet<string> = new Set(),
   rewriteRelativeImport?: (importPath: string) => string,
+  options?: {
+    /**
+     * Skip `export const` / `export function` value declarations — the
+     * adapter already emitted them inside its module-scope section, in
+     * source order (see `TemplateSections.moduleConstantsIncludeExports`).
+     * `export { … } [from '…']` specifier blocks are still emitted.
+     */
+    skipValueDeclarations?: boolean
+  },
 ): string | null {
   const lines: string[] = []
 
-  for (const constant of ir.metadata.localConstants) {
+  for (const constant of options?.skipValueDeclarations ? [] : ir.metadata.localConstants) {
     if (!constant.isExported) continue
     const keyword = constant.declarationKind ?? 'const'
     if (!constant.value) {
@@ -38,7 +47,7 @@ export function generateModuleExports(
     lines.push(`export ${keyword} ${constant.name} = ${constant.value}`)
   }
 
-  for (const func of ir.metadata.localFunctions) {
+  for (const func of options?.skipValueDeclarations ? [] : ir.metadata.localFunctions) {
     if (!func.isExported) continue
     // Prefer the source-verbatim signature so type predicates and explicit
     // `:unknown` parameter annotations survive — see FunctionInfo.typedParams