@barefootjs/jsx 0.18.4 → 0.18.7

package/src/jsx-to-ir.ts

@@ -34,7 +34,7 @@ import {
   AttrValueOf,
 } from './types.ts'
 import { type AnalyzerContext, type MultiReturnJsxInfo, getSourceLocation, collectReactiveGetterNames } from './analyzer-context.ts'
-import { parseExpression, isSupported, parseBlockBody, foldBlockToExpr, predicateTernaryToLogical, tsNodeToParsedExpr, sortComparatorFromArrow, stringifyParsedExpr, cssKebabCase, type ParsedExpr } from './expression-parser.ts'
+import { parseExpression, isSupported, parseBlockBody, foldBlockToExpr, predicateTernaryToLogical, tsNodeToParsedExpr, sortComparatorFromArrow, stringifyParsedExpr, cssKebabCase, CALLBACK_METHODS, type ParsedExpr } from './expression-parser.ts'
 import type { IRLoopSort, FunctionInfo } from './types.ts'
 import { formatParamWithType } from './module-exports.ts'
 import { createError, ErrorCodes, internalInvariant } from './errors.ts'
@@ -48,7 +48,7 @@ import { resolveFreeRefs, isNameBound as isNameBoundInEnv, type BindingEnvironme
 import { computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx } from './analyzer.ts'
 import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
-import { toHTMLAttrName } from '@barefootjs/shared'
+import { toHTMLAttrName, decodeEntities } from '@barefootjs/shared'
 
 // =============================================================================
 // Transform Context
@@ -82,6 +82,17 @@ interface TransformContext {
   _destructuredPropNames?: Set<string> | null
   /** Active loop parameter names for slotId assignment to loop-param-dependent expressions */
   loopParams: Set<string>
+  /**
+   * 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
+   * 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
+   * from one IR-computed value instead of each adapter re-deriving
+   * nesting depth its own way (#2168 nested-loop-outer-binding).
+   */
+  loopDepth: number
   /** Counter for async boundary IDs (a0, a1, ...) */
   asyncIdCounter: number
   /** Counter for <Region> structural index (0, 1, ...) within a file. */
@@ -280,8 +291,21 @@ function exprHasFunctionCalls(expr: ts.Expression): boolean {
  * Returns undefined if no rewriting is needed (SolidJS-style or no props).
  */
 function rewriteBarePropRefs(text: string, expr: ts.Node, ctx: TransformContext): string | undefined {
-  const propNames = getDestructuredPropNames(ctx)
+  let propNames = getDestructuredPropNames(ctx)
   if (!propNames) return undefined
+  // #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)))
+    if (filtered.size === 0) return undefined
+    propNames = filtered
+  }
   // #1425: union any prop refs that `expr` reaches via branch-local
   // text substitution. The AST walk in `rewriteBarePropRefsCore`
   // sees only `expr`'s original AST, so a prop ref introduced via
@@ -395,6 +419,7 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
     isRoot: true,
     insideComponentChildren: false,
     loopParams: new Set(),
+    loopDepth: 0,
     patterns: {
       signals: analyzer.signals.map(s => ({
         getter: s.getter,
@@ -579,20 +604,34 @@ function parseValueExpr(trimmed: string): ParsedExpr {
   return parseExpression(trimmed.startsWith('{') ? `(${trimmed})` : trimmed)
 }
 
+/** Shared empty-set default for `attachParsedExpressions`/`resolveCallbackMethodFunctionReferences`'s `bound` param — avoids a fresh allocation per call when nothing is shadowed. */
+const EMPTY_BOUND: ReadonlySet<string> = new Set()
+
 /**
  * Attach `parsed` (`parseExpression(expr.trim())`) to every `expression` node
  * in the tree, so SSR adapters emit from the structured tree instead of each
  * re-parsing the string at emit time. Best-effort: a node this walk misses (or
  * an empty `expr`) simply has no `parsed`, and the adapter falls back to
  * parsing — so under-coverage is safe, never a behavioural change.
+ *
+ * Every parse is run through {@link resolveCallbackMethodFunctionReferences}
+ * (#2206) so a bare-identifier `.map`/`.filter`/… callback (`tags.map(format)`)
+ * resolves to its declaration wherever it can appear — text/attr/prop/provider
+ * expressions and the loop-array expression alike — not just one hardcoded
+ * spot. `bound` carries the enclosing loop(s)' `param`/`index` names down
+ * into that resolution (Fable review, #2214) so a loop item variable that
+ * happens to share a name with a module-scope const/function shadows it,
+ * same as real JS scoping — resolution stays off within that loop's body.
  */
-function attachParsedExpressions(node: IRNode): void {
+function attachParsedExpressions(node: IRNode, analyzer: AnalyzerContext, bound: ReadonlySet<string> = EMPTY_BOUND): void {
+  const parse = (trimmed: string) => resolveCallbackMethodFunctionReferences(parseExpression(trimmed), analyzer, bound)
+  const parseValue = (trimmed: string) => resolveCallbackMethodFunctionReferences(parseValueExpr(trimmed), analyzer, bound)
   if (node.type === 'expression') {
     const trimmed = node.expr.trim()
-    if (trimmed) node.parsed = parseExpression(trimmed)
+    if (trimmed) node.parsed = parse(trimmed)
   } else if (node.type === 'conditional' || node.type === 'if-statement') {
     const trimmed = node.condition.trim()
-    if (trimmed) node.parsedCondition = parseExpression(trimmed)
+    if (trimmed) node.parsedCondition = parse(trimmed)
   }
   // Attach `parsed` to every expression-valued attribute / prop so adapters can
   // lower from the tree instead of re-parsing the string. Element attrs,
@@ -603,23 +642,23 @@ function attachParsedExpressions(node: IRNode): void {
     for (const attr of node.attrs) {
       if (attr.value.kind === 'expression') {
         const trimmed = attr.value.expr.trim()
-        if (trimmed) attr.value.parsed = parseValueExpr(trimmed)
+        if (trimmed) attr.value.parsed = parseValue(trimmed)
       } else if (attr.value.kind === 'spread') {
         const trimmed = attr.value.expr.trim()
-        if (trimmed) attr.value.parsed = parseExpression(trimmed)
+        if (trimmed) attr.value.parsed = parse(trimmed)
       }
     }
   } else if (node.type === 'component') {
     for (const prop of node.props) {
       if (prop.value.kind === 'expression') {
         const trimmed = prop.value.expr.trim()
-        if (trimmed) prop.value.parsed = parseValueExpr(trimmed)
+        if (trimmed) prop.value.parsed = parseValue(trimmed)
       }
     }
   } else if (node.type === 'provider') {
     if (node.valueProp.value.kind === 'expression') {
       const trimmed = node.valueProp.value.expr.trim()
-      if (trimmed) node.valueProp.value.parsed = parseValueExpr(trimmed)
+      if (trimmed) node.valueProp.value.parsed = parseValue(trimmed)
     }
   }
   switch (node.type) {
@@ -627,46 +666,54 @@ function attachParsedExpressions(node: IRNode): void {
     case 'component':
     case 'fragment':
     case 'provider':
-      for (const child of node.children) attachParsedExpressions(child)
+      for (const child of node.children) attachParsedExpressions(child, analyzer, bound)
       break
     case 'async':
-      attachParsedExpressions(node.fallback)
-      for (const child of node.children) attachParsedExpressions(child)
+      attachParsedExpressions(node.fallback, analyzer, bound)
+      for (const child of node.children) attachParsedExpressions(child, analyzer, bound)
       break
     case 'loop': {
       // Attach the parse of the SAME `array` string the adapters consume
       // (the Go adapter's scalar-literal loop typing reads `loop.array` /
       // `nested.loopArray`, which is exactly `loop.array`), so it can read
-      // the tree instead of re-parsing with `ts.createSourceFile`.
+      // the tree instead of re-parsing with `ts.createSourceFile`. The array
+      // expression itself is evaluated in the OUTER scope (before the loop's
+      // own `param`/`index` exist), so it parses against the unextended `bound`.
       const trimmedArray = node.array.trim()
-      if (trimmedArray) node.arrayParsed = parseExpression(trimmedArray)
-      for (const child of node.children) attachParsedExpressions(child)
+      if (trimmedArray) node.arrayParsed = parse(trimmedArray)
+      // The loop's item/index variables shadow any same-named module-scope
+      // const/function for everything inside the loop body (Fable review,
+      // #2214) — mirrors an arrow's own params in `resolveCallbackMethodFunctionReferences`.
+      const loopBound = new Set(bound)
+      loopBound.add(node.param)
+      if (node.index) loopBound.add(node.index)
+      for (const child of node.children) attachParsedExpressions(child, analyzer, loopBound)
       // Loops also hold expression nodes off the main `children` array.
       if (node.childComponent) {
-        for (const child of node.childComponent.children) attachParsedExpressions(child)
+        for (const child of node.childComponent.children) attachParsedExpressions(child, analyzer, loopBound)
       }
       for (const nested of node.nestedComponents ?? []) {
-        for (const child of nested.children) attachParsedExpressions(child)
+        for (const child of nested.children) attachParsedExpressions(child, analyzer, loopBound)
       }
       for (const frag of node.flatMapCallback?.fragments ?? []) {
-        attachParsedExpressions(frag.ir)
+        attachParsedExpressions(frag.ir, analyzer, loopBound)
       }
       break
     }
     case 'conditional':
-      attachParsedExpressions(node.whenTrue)
-      attachParsedExpressions(node.whenFalse)
+      attachParsedExpressions(node.whenTrue, analyzer, bound)
+      attachParsedExpressions(node.whenFalse, analyzer, bound)
       break
     case 'if-statement':
-      attachParsedExpressions(node.consequent)
-      if (node.alternate) attachParsedExpressions(node.alternate)
+      attachParsedExpressions(node.consequent, analyzer, bound)
+      if (node.alternate) attachParsedExpressions(node.alternate, analyzer, bound)
       break
   }
 }
 
 export function jsxToIR(analyzer: AnalyzerContext): IRNode | null {
   const root = buildIRRoot(analyzer)
-  if (root) attachParsedExpressions(root)
+  if (root) attachParsedExpressions(root, analyzer)
   return root
 }
 
@@ -1563,7 +1610,12 @@ function transformText(node: ts.JsxText, ctx: TransformContext): IRText | null {
 
   return {
     type: 'text',
-    value: text,
+    // JSX decodes character references at parse time (`&copy;` IS the
+    // text `©`), so the IR carries the DECODED value — the semantics —
+    // and each adapter re-escapes for its own emission context.
+    // Decode AFTER whitespace normalization: `&nbsp;` yields U+00A0,
+    // which `\s+` would otherwise collapse into a plain space.
+    value: decodeEntities(text),
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
   }
 }
@@ -2483,6 +2535,31 @@ function isIteratorShapeCall(
   return { array: node.expression.expression, shape: name }
 }
 
+/**
+ * Check if a node is the STATIC `Object.entries(x)` / `Object.keys(x)` /
+ * `Object.values(x)` call form (#2168 object-entries-map) — the
+ * one-argument form where `x` is a plain object/Record being iterated,
+ * as opposed to {@link isIteratorShapeCall}'s zero-arg instance-method
+ * form (`arr.entries()`) on an actual array. Returns the object
+ * expression (any expression — `props.x`, `x ?? {}`, not just a bare
+ * identifier) and the iteration shape so `transformMapCall` can strip
+ * the `Object.<method>(...)` wrapper and record it on the IRLoop as
+ * `objectIteration` (see that field's docstring in `types.ts` for why
+ * this is a distinct field from `iterationShape`, not a shared one).
+ */
+function isObjectIteratorCall(
+  node: ts.Expression,
+): { object: ts.Expression; shape: 'entries' | 'keys' | 'values' } | null {
+  if (!ts.isCallExpression(node)) return null
+  if (!ts.isPropertyAccessExpression(node.expression)) return null
+  if (!ts.isIdentifier(node.expression.expression)) return null
+  if (node.expression.expression.text !== 'Object') return null
+  if (node.arguments.length !== 1) return null
+  const name = node.expression.name.text
+  if (name !== 'entries' && name !== 'keys' && name !== 'values') return null
+  return { object: node.arguments[0], shape: name }
+}
+
 type SortExtractionResult = {
   result: IRLoopSort | null
   unsupportedReason?: string
@@ -2590,8 +2667,8 @@ function extractSortComparator(
  * vs. unresolved) is decided by the caller, not here.
  */
 function resolveSortComparatorIdentifier(name: string, ctx: TransformContext): ts.Expression | null {
-  const constInfo = findLocalConst(name, ctx)
-  const fnInfo = findLocalFunction(name, ctx)
+  const constInfo = findLocalConst(name, ctx.analyzer)
+  const fnInfo = findLocalFunction(name, ctx.analyzer)
   if (constInfo && fnInfo) return null
   if (constInfo) {
     const ast = parseConstInitializer(constInfo)
@@ -2604,6 +2681,149 @@ function resolveSortComparatorIdentifier(name: string, ctx: TransformContext): t
   return null
 }
 
+/**
+ * Resolve a bare-identifier callback passed to a value-position higher-order
+ * array method (`tags.map(format)`, `.filter`, `.sort`, … — any name in
+ * {@link CALLBACK_METHODS}, #2206) to its underlying arrow / function-
+ * expression node — the SAME one-hop, ambiguity-refuses lookup #2090
+ * established for `.sort(fnref)` comparators (`resolveSortComparatorIdentifier`
+ * above). Kept as its own small function (mirroring the existing
+ * `resolveInterleaveTagIdentifier` precedent below) rather than sharing code
+ * with the sort resolver, so each call site's refusal semantics stay
+ * independently reviewable.
+ *
+ * Only needs `AnalyzerContext` (not a full `TransformContext`) because its
+ * caller, {@link resolveCallbackMethodFunctionReferences}, runs as a
+ * post-parse pass over an already-built `ParsedExpr` tree — no live
+ * `ts.Node`/source-file binding is available or needed, since
+ * `parseConstInitializer` / `parseFunctionInfoAsExpr` re-parse the
+ * analyzer's stored declaration TEXT into a fresh, isolated source file.
+ */
+function resolveCallbackMethodFunctionReferenceIdentifier(name: string, analyzer: AnalyzerContext): ts.Expression | null {
+  const constInfo = findLocalConst(name, analyzer)
+  const fnInfo = findLocalFunction(name, analyzer)
+  if (constInfo && fnInfo) return null
+  if (constInfo) {
+    const ast = parseConstInitializer(constInfo)
+    return ast && (ts.isArrowFunction(ast) || ts.isFunctionExpression(ast)) ? ast : null
+  }
+  if (fnInfo) {
+    const ast = parseFunctionInfoAsExpr(fnInfo)
+    return ast && (ts.isArrowFunction(ast) || ts.isFunctionExpression(ast)) ? ast : null
+  }
+  return null
+}
+
+/**
+ * Post-parse pass (#2206): walk a `ParsedExpr` tree and resolve every
+ * `<recv>.<CALLBACK_METHODS method>(<bare identifier>, …rest)` call's
+ * callback argument to its declaration, so `tags.map(format).join(' ')`
+ * compiles exactly as if `format`'s body had been written inline
+ * (`tags.map(t => '#' + t).join(' ')`) — the shape `asCallbackMethodCall`
+ * (expression-parser.ts) already recognizes and every adapter's `map_eval`
+ * (#2073) already lowers.
+ *
+ * Runs AFTER `parseExpression`, not threaded into it, because the
+ * value-returning `.map(cb)` form is recognized generically downstream of
+ * parsing (`asCallbackMethodCall`'s `arrow.kind !== 'arrow'` check), not
+ * during it — `convertNode` already happily produces a generic `call` node
+ * with an `identifier` arg for `tags.map(format)` with no special-casing
+ * needed there. An unresolvable reference (import, non-function const,
+ * alias chain, cross-kind ambiguity — see
+ * {@link resolveCallbackMethodFunctionReferenceIdentifier}) or a resolved
+ * body that can't fold to a single expression is left untouched: the
+ * `identifier` arg passes through as-is, and `asCallbackMethodCall`'s
+ * existing arrow-kind check still refuses it with the current BF101,
+ * unchanged.
+ *
+ * A spliced-in resolved arrow's OWN body is not re-walked (`visit` returns
+ * it as-is rather than recursing) — a bare-identifier callback declared
+ * INSIDE another resolved declaration (`const outer = xs => xs.map(inner).join(',')`
+ * used as `rows.map(outer)`) stays unresolved and BF101-refuses, same as
+ * before #2206. This is a deliberate one-hop limit, not an oversight: naively
+ * recursing risks an infinite loop on a self-referential declaration
+ * (`const f = xs => xs.map(f)`), which would need a resolution stack to
+ * detect — out of scope here. Fails safe (refuses loudly rather than
+ * mis-rendering); see the pinned-refusal test in map-function-reference.test.ts.
+ *
+
+ * `bound` tracks names that are lexically shadowed at the current walk
+ * position — an enclosing arrow's own params (`rows.map(fn => fn.tags.map(fn)…)`
+ * — so a bare identifier that refers to a PARAMETER rather than a same-file
+ * const/function is never resolved against the const/function tables
+ * (Fable review, #2214): it grows exactly like {@link freeVarsInBody}'s own
+ * `bound` set, at the SAME `arrow` case. The initial call from
+ * `attachParsedExpressions` seeds it with the enclosing loop's `param`/
+ * `index` too (a loop's item variable shadows a same-named module const the
+ * same way a callback arrow's param does — `origin.freeRefs` already tags
+ * such a name `kind: 'render-item'`, this walk now honors it).
+ */
+function resolveCallbackMethodFunctionReferences(
+  expr: ParsedExpr,
+  analyzer: AnalyzerContext,
+  bound: ReadonlySet<string> = EMPTY_BOUND,
+): ParsedExpr {
+  function visit(e: ParsedExpr, bound: ReadonlySet<string>): ParsedExpr {
+    switch (e.kind) {
+      case 'literal':
+      case 'identifier':
+      case 'regex':
+      case 'unsupported':
+        return e
+      case 'call': {
+        const callee = visit(e.callee, bound)
+        const args = e.args.map(a => visit(a, bound))
+        if (
+          callee.kind === 'member' && !callee.computed &&
+          CALLBACK_METHODS.has(callee.property) &&
+          args[0]?.kind === 'identifier' &&
+          !bound.has(args[0].name)
+        ) {
+          const resolved = resolveCallbackMethodFunctionReferenceIdentifier(args[0].name, analyzer)
+          const arrow = resolved ? tsNodeToParsedExpr(resolved) : null
+          if (arrow && arrow.kind === 'arrow') args[0] = arrow
+        }
+        return { ...e, callee, args }
+      }
+      case 'member':
+        return { ...e, object: visit(e.object, bound) }
+      case 'index-access':
+        return { ...e, object: visit(e.object, bound), index: visit(e.index, bound) }
+      case 'binary':
+      case 'logical':
+        return { ...e, left: visit(e.left, bound), right: visit(e.right, bound) }
+      case 'unary':
+        return { ...e, argument: visit(e.argument, bound) }
+      case 'conditional':
+        return { ...e, test: visit(e.test, bound), consequent: visit(e.consequent, bound), alternate: visit(e.alternate, bound) }
+      case 'template-literal':
+        return { ...e, parts: e.parts.map(p => (p.type === 'expression' ? { ...p, expr: visit(p.expr, bound) } : p)) }
+      case 'array-literal':
+        return { ...e, elements: e.elements.map(el => visit(el, bound)) }
+      case 'array-method':
+        // `e.args` is a fixed-length tuple for some `method` variants (e.g.
+        // `flat`'s `args: []`) — `.map(visit)` preserves length/order (a
+        // callback resolution never adds/removes args), so this is a
+        // same-shape cast, not a structural change. TS can't verify the
+        // per-`method` tuple-length invariant across a `.map`, hence the
+        // whole-object cast rather than a narrower one.
+        return {
+          ...e,
+          object: visit(e.object, bound),
+          args: e.args.map(a => visit(a, bound)),
+          ...(e.method === 'flat' && e.depthExpr ? { depthExpr: visit(e.depthExpr, bound) } : {}),
+        } as ParsedExpr
+      case 'object-literal':
+        return { ...e, properties: e.properties.map(p => ({ ...p, value: visit(p.value, bound) })) }
+      case 'arrow': {
+        const inner = e.params.length === 0 ? bound : new Set([...bound, ...e.params])
+        return { ...e, body: visit(e.body, inner) }
+      }
+    }
+  }
+  return visit(expr, bound)
+}
+
 /**
  * Result type for extractFilterPredicate. The predicate is always an expression:
  * a block body is normalized to one via `foldBlockToExpr` +
@@ -3246,6 +3466,10 @@ function transformMapCall(
   // 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
+  // This loop's own depth (0 = outermost) is however many enclosing
+  // loops are already active, captured before `ctx.loopDepth` below is
+  // bumped for THIS loop's own descendants.
+  const depth = ctx.loopDepth
 
   const propAccess = node.expression as ts.PropertyAccessExpression
   const mapSource = propAccess.expression
@@ -3271,6 +3495,7 @@ function transformMapCall(
   let templateMapPreamble: string | undefined
   let typedMapPreamble: string | undefined
   let iterationShape: 'entries' | 'keys' | undefined
+  let objectIteration: 'entries' | 'keys' | 'values' | undefined
 
   // Helper to set both array and templateArray
   const setArray = (node: ts.Expression) => {
@@ -3284,8 +3509,11 @@ function transformMapCall(
   // adapters emit the right loop variable bindings. `.values()` is a
   // no-op (same as plain `.map()`) so it's stripped but not recorded.
   // The inner expression (after stripping) feeds into the standard
-  // filter/sort chain detection below.
-  let chainSource = mapSource
+  // filter/sort chain detection below. Widened to `ts.Expression` (not
+  // narrowed to `mapSource`'s own `LeftHandSideExpression` type) since
+  // `isObjectIteratorCall`'s stripped argument can be any expression
+  // (`x ?? {}`, not just a `LeftHandSideExpression`).
+  let chainSource: ts.Expression = mapSource
   const iteratorInfo = isIteratorShapeCall(mapSource)
   if (iteratorInfo) {
     chainSource = iteratorInfo.array
@@ -3295,6 +3523,18 @@ function transformMapCall(
       iterationShape = 'keys'
     }
     // 'values' is a no-op — same as plain .map()
+  } else {
+    // Detect the STATIC `Object.entries(x)` / `.keys(x)` / `.values(x)`
+    // form (#2168 object-entries-map) — see `isObjectIteratorCall`'s and
+    // `IRLoop.objectIteration`'s docstrings for why this is a SEPARATE
+    // shape from the array-instance-method case above, not a shared one.
+    // Unlike that case, `'values'` DOES need recording here (it isn't a
+    // no-op: `x` itself isn't iterable as a plain object).
+    const objectIteratorInfo = isObjectIteratorCall(mapSource)
+    if (objectIteratorInfo) {
+      chainSource = objectIteratorInfo.object
+      objectIteration = objectIteratorInfo.shape
+    }
   }
 
   const filterInfo = isFilterCall(chainSource)
@@ -3407,14 +3647,19 @@ function transformMapCall(
           setArray(innerSort.array)
         }
       } else {
-        // Simple filter().map()
-        array = ctx.getJS(filterInfo.array)
-        arrayExpr = filterInfo.array
+        // Simple filter().map(). `setArray` (not a bare `array =`
+        // assignment) so `templateArray` carries the `_p.`-rewritten form —
+        // the module-scope `template:` lambda can't see init's destructured
+        // prop locals, and a bare destructured name there threw
+        // `ReferenceError` at runtime (#2222).
+        setArray(filterInfo.array)
       }
     }
   } else {
-    array = ctx.getJS(chainSource)
-    arrayExpr = chainSource
+    // Plain `.map()` fallback — same `setArray` requirement as above
+    // (#2222): this is the most common loop shape and was the primary
+    // repro for the bare-destructured-name ReferenceError.
+    setArray(chainSource)
   }
 
   // Get callback function
@@ -3445,8 +3690,12 @@ function transformMapCall(
       // `.entries()` synthesises `[index, value]` — when the callback
       // destructures exactly two array elements, extract the names into
       // `index` and `param` so the loop renders with proper bindings and
-      // the BF104 destructure-param refusal doesn't fire.
-      if (iterationShape === 'entries' && ts.isArrayBindingPattern(firstParam.name)) {
+      // the BF104 destructure-param refusal doesn't fire. `Object.entries(x)`
+      // (`objectIteration === 'entries'`) synthesises the SAME `[key,
+      // value]` 2-tuple shape — `index` just holds a string key instead
+      // of a numeric position — so it reuses this exact extraction.
+      const isEntriesShape = iterationShape === 'entries' || objectIteration === 'entries'
+      if (isEntriesShape && ts.isArrayBindingPattern(firstParam.name)) {
         const elements = firstParam.name.elements.filter(
           el => !ts.isOmittedExpression(el),
         )
@@ -3485,7 +3734,7 @@ function transformMapCall(
         }
       }
     }
-    if (callback.parameters.length > 1 && iterationShape !== 'entries') {
+    if (callback.parameters.length > 1 && iterationShape !== 'entries' && objectIteration !== 'entries') {
       const secondParam = callback.parameters[1]
       index = secondParam.name.getText(ctx.sourceFile)
       if (secondParam.type) {
@@ -3504,6 +3753,7 @@ function transformMapCall(
       ctx.loopParams.add(param)
     }
     if (index) ctx.loopParams.add(index)
+    ctx.loopDepth++
 
     // Logical control flow (`cond && <X/>`, `a ?? themeLogo()`) as the map
     // body. This is not a JSX literal, ternary, or block, so without this
@@ -3626,6 +3876,7 @@ function transformMapCall(
       ctx.loopParams.delete(param)
     }
     if (index) ctx.loopParams.delete(index)
+    ctx.loopDepth--
   }
 
   // If no JSX children were found (e.g., callback returns a function call),
@@ -3705,6 +3956,16 @@ function transformMapCall(
     !isSignalOrMemoArray(array, ctx)
     && !isDirectPropArray
     && !hasCalls
+    // `objectIteration` (#2168 object-entries-map): `array` here is the
+    // STRIPPED object expression (`Object.entries(x)`'s `x`), which can
+    // itself be a static module-scope const object literal and would
+    // otherwise satisfy every check above — but a plain OBJECT has no
+    // `.forEach()`/`.map()` (the static-array client codegen's own
+    // methods), unlike an actual array literal. Force the dynamic
+    // `mapArray()` path instead, which this shape's client-JS array-expr
+    // reconstruction (`applyObjectIterationWrap`, `ir-to-client-js/utils.ts`)
+    // already handles correctly.
+    && !objectIteration
 
   // Collect nested components for both static and dynamic arrays.
   // Static arrays: needed for initChild hydration.
@@ -3744,6 +4005,8 @@ function transformMapCall(
     sortComparator,
     chainOrder,
     iterationShape,
+    objectIteration,
+    depth,
     clientOnly: isClientOnly || undefined,
     mapPreamble,
     templateMapPreamble,
@@ -4157,9 +4420,12 @@ function getAttributeValue(attr: ts.JsxAttribute, ctx: TransformContext): AttrVa
     return AttrValueOf.booleanAttr()
   }
 
-  // String literal: <div id="main" />
+  // String literal: <div id="main" />. JSX decodes character references
+  // in quoted attribute values just like in text children, so the IR
+  // carries the decoded string (`title="Fish &amp; Chips"` IS the value
+  // `Fish & Chips`); adapters re-escape on emit.
   if (ts.isStringLiteral(attr.initializer)) {
-    return AttrValueOf.literal(attr.initializer.text)
+    return AttrValueOf.literal(decodeEntities(attr.initializer.text))
   }
 
   // Expression: <div class={className} />
@@ -4351,7 +4617,7 @@ function tryResolveTemplateSpanFromConst(
 ): IRTemplatePart[] | null {
   // ${IDENT}
   if (ts.isIdentifier(expr)) {
-    const constInfo = findLocalConst(expr.text, ctx)
+    const constInfo = findLocalConst(expr.text, ctx.analyzer)
     if (!constInfo) return null
     const ast = parseConstInitializer(constInfo)
     if (!ast) return null
@@ -4364,7 +4630,7 @@ function tryResolveTemplateSpanFromConst(
   // ${IDENT[KEY]}
   if (ts.isElementAccessExpression(expr)) {
     if (!ts.isIdentifier(expr.expression)) return null
-    const constInfo = findLocalConst(expr.expression.text, ctx)
+    const constInfo = findLocalConst(expr.expression.text, ctx.analyzer)
     if (!constInfo) return null
     const ast = parseConstInitializer(constInfo)
     if (!ast || !ts.isObjectLiteralExpression(ast)) return null
@@ -4421,8 +4687,8 @@ function tryResolveTemplateSpanFromConst(
  *
  * Returns undefined when no const matches.
  */
-function findLocalConst(name: string, ctx: TransformContext) {
-  const matches = ctx.analyzer.localConstants.filter(c => c.name === name)
+function findLocalConst(name: string, analyzer: AnalyzerContext) {
+  const matches = analyzer.localConstants.filter(c => c.name === name)
   if (matches.length === 0) return undefined
   // Prefer the innermost (non-module) binding; fall back to whatever's
   // there if every match is at module scope.
@@ -4439,8 +4705,8 @@ function findLocalConst(name: string, ctx: TransformContext) {
  *
  * Returns undefined when no local function matches.
  */
-function findLocalFunction(name: string, ctx: TransformContext) {
-  const matches = ctx.analyzer.localFunctions.filter(f => f.name === name)
+function findLocalFunction(name: string, analyzer: AnalyzerContext) {
+  const matches = analyzer.localFunctions.filter(f => f.name === name)
   if (matches.length === 0) return undefined
   const fnScoped = matches.filter(f => !f.isModule)
   const pool = fnScoped.length > 0 ? fnScoped : matches
@@ -4530,7 +4796,15 @@ function tryResolveIdentifierAsTemplateLiteral(
   ident: ts.Identifier,
   ctx: TransformContext,
 ): IRTemplatePart[] | null {
-  const constInfo = findLocalConst(ident.text, ctx)
+  // #2222/#2235: at this transform position the identifier may be an
+  // enclosing loop callback's own (shadowing) parameter — folding the
+  // 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
+  const constInfo = findLocalConst(ident.text, ctx.analyzer)
   if (!constInfo) return null
   const ast = parseConstInitializer(constInfo)
   if (!ast) return null
@@ -4740,8 +5014,8 @@ function tryDesugarInterleaveTaggedTemplate(
  * followed, matching that precedent. Returns null when nothing resolves.
  */
 function resolveInterleaveTagIdentifier(name: string, ctx: TransformContext): ts.Expression | null {
-  const constInfo = findLocalConst(name, ctx)
-  const fnInfo = findLocalFunction(name, ctx)
+  const constInfo = findLocalConst(name, ctx.analyzer)
+  const fnInfo = findLocalFunction(name, ctx.analyzer)
   // A name bound BOTH as a const and as a `function` declaration is the
   // same cross-kind ambiguity `resolveSortComparatorIdentifier` refuses:
   // it can only occur across scopes, and `FunctionInfo.isModule` reflects