@barefootjs/jsx 0.1.3 → 1.0.0

package/src/html-constants.ts

@@ -1,29 +1,6 @@
 /**
- * HTML boolean attributes that should be rendered without values.
- *
- * When true: render as attribute name only (e.g., `checked`)
- * When false/null/undefined: omit from output entirely
+ * HTML boolean attributes — re-exported from the shared classifier so the
+ * compiler keeps its existing import path while the source of truth lives
+ * in @barefootjs/shared/dom-prop.
  */
-export const BOOLEAN_ATTRS = new Set([
-  'checked',
-  'disabled',
-  'readonly',
-  'selected',
-  'required',
-  'hidden',
-  'autofocus',
-  'autoplay',
-  'controls',
-  'loop',
-  'muted',
-  'open',
-  'multiple',
-  'novalidate',
-])
-
-/**
- * Check if an attribute name is a boolean attribute.
- */
-export function isBooleanAttr(name: string): boolean {
-  return BOOLEAN_ATTRS.has(name.toLowerCase())
-}
+export { BOOLEAN_ATTRS, isBooleanAttr } from '@barefootjs/shared'

package/src/index.ts

@@ -246,15 +246,20 @@ export type { LoopChainInputs } from './loop-chain'
 // Debug analysis
 export {
   buildComponentGraph,
+  buildComponentAnalysis,
   buildGraphFromIR,
+  buildEventSummary,
+  buildLoopSummary,
   traceUpdatePath,
   formatComponentGraph,
   formatUpdatePath,
+  formatEventSummary,
+  formatLoopSummary,
   formatSignalTrace,
   generateStaticTrace,
   graphToJSON,
 } from './debug'
-export type { ComponentGraph, SignalNode, MemoNode, EffectNode, DomBinding, UpdatePath, SignalTrace } from './debug'
+export type { ComponentGraph, ComponentAnalysis, SignalNode, MemoNode, EffectNode, DomBinding, UpdatePath, SignalTrace, EventBinding, SetterRef, EventSummary, LoopInfo, LoopChildBinding, LoopSummary } from './debug'
 export type { WrapReason } from './ir-to-client-js/reactivity'
 
 // HTML constants

package/src/ir-to-client-js/collect-elements.ts

@@ -231,6 +231,7 @@ export function collectInnerLoops(
           key: n.key,
           markerId: n.markerId,
           bodyIsMultiRoot: n.bodyIsMultiRoot,
+          iterationShape: n.iterationShape,
           containerSlotId: scope.parentSlotId,
           template,
           mapPreamble: n.mapPreamble,
@@ -563,6 +564,7 @@ export function collectElements(
         key: l.key,
         markerId: l.markerId,
         bodyIsMultiRoot: l.bodyIsMultiRoot,
+        iterationShape: l.iterationShape,
         template,
         staticItemTemplate,
         childEventHandlers: childHandlers,
@@ -896,6 +898,7 @@ function collectBranchLoops(
         key: n.key,
         markerId: n.markerId,
         bodyIsMultiRoot: n.bodyIsMultiRoot,
+        iterationShape: n.iterationShape,
         template: childTemplate,
         containerSlotId: containerSlot,
         mapPreamble: n.mapPreamble ?? null,

package/src/ir-to-client-js/emit-reactive.ts

@@ -8,6 +8,7 @@ import type { AttrMeta } from '../types'
 import { isBooleanAttr } from '../html-constants'
 import type { ClientJsContext } from './types'
 import { toHtmlAttrName, varSlotId, PROPS_PARAM } from './utils'
+import { createTemplateAwareStringProtector } from './html-template'
 
 /**
  * Generate JS statements to update a DOM attribute reactively.
@@ -53,10 +54,11 @@ export function emitAttrUpdate(target: string, attrName: string, expression: str
  * Only applies when the component uses destructured props (not props.xxx style).
  */
 export function rewriteDestructuredPropsInExpr(expr: string, ctx: ClientJsContext): string {
-  // Skip if the component already uses props object access (not destructuring)
   if (ctx.propsObjectName) return expr
 
-  let result = expr
+  const { protect, restore } = createTemplateAwareStringProtector()
+  let result = protect(expr)
+
   for (const prop of ctx.propsParams) {
     if (prop.name === 'children') continue
     const pattern = new RegExp(`(?<![-.])\\b${prop.name}\\b`, 'g')
@@ -69,7 +71,7 @@ export function rewriteDestructuredPropsInExpr(expr: string, ctx: ClientJsContex
     result = result.replace(new RegExp(`(?<![-.])\\b${prop.name}\\b`, 'g'), replacement)
   }
 
-  return result
+  return restore(result)
 }
 
 /** Emit createEffect blocks that update text nodes for reactive expressions. */
@@ -152,8 +154,6 @@ export function emitReactiveAttributeUpdates(lines: string[], ctx: ClientJsConte
       lines.push(`  createEffect(() => {`)
       lines.push(`    if (_${v}) {`)
       for (const attr of attrs) {
-        // Rewrite destructured prop references to props.xxx for live reactivity.
-        // Destructured props are const-captured once; effects must read from props object.
         const expression = rewriteDestructuredPropsInExpr(attr.expression, ctx)
         for (const stmt of emitAttrUpdate(`_${v}`, attr.attrName, expression, attr)) {
           lines.push(`      ${stmt}`)

package/src/ir-to-client-js/html-template.ts

@@ -36,6 +36,62 @@ export function createStringProtector(): {
   return { protect, restore }
 }
 
+/**
+ * Split a template literal body into static segments and `${...}` interpolations,
+ * correctly handling nested braces (e.g. object literals inside interpolations).
+ */
+export function splitTemplateInterpolations(inner: string): string[] {
+  const parts: string[] = []
+  let i = 0
+  let segStart = 0
+  while (i < inner.length) {
+    if (inner[i] === '$' && inner[i + 1] === '{') {
+      if (i > segStart) parts.push(inner.slice(segStart, i))
+      let depth = 1
+      let j = i + 2
+      while (j < inner.length && depth > 0) {
+        if (inner[j] === '{') depth++
+        else if (inner[j] === '}') depth--
+        if (depth > 0) j++
+      }
+      j++
+      parts.push(inner.slice(i, j))
+      i = j
+      segStart = j
+    } else {
+      i++
+    }
+  }
+  if (segStart < inner.length) parts.push(inner.slice(segStart))
+  return parts
+}
+
+/**
+ * Protect both template-literal static segments AND quoted string literals
+ * from regex-based prop substitution. Used by prop-rewrite.ts (Phase 1)
+ * and emit-reactive.ts (Phase 2) to avoid corrupting CSS selectors and
+ * class values during prop name replacement.
+ */
+export function createTemplateAwareStringProtector(): {
+  protect: (s: string) => string
+  restore: (s: string) => string
+} {
+  const stash: string[] = []
+  const save = (s: string) => { const i = stash.length; stash.push(s); return `__STRLIT_${i}__` }
+  const protect = (s: string): string => {
+    s = s.replace(/`([^`]*)`/g, (_full, inner: string) => {
+      const parts = splitTemplateInterpolations(inner)
+      return '`' + parts.map(p => p.startsWith('${') ? p : save(p)).join('') + '`'
+    })
+    s = s.replace(/'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g, m => save(m))
+    return s
+  }
+  const restore = (s: string): string => {
+    return s.replace(/__STRLIT_(\d+)__/g, (_, i) => stash[Number(i)])
+  }
+  return { protect, restore }
+}
+
 const VOID_ELEMENTS = new Set([
   'area', 'base', 'br', 'col', 'embed', 'hr', 'img',
   'input', 'link', 'meta', 'param', 'source', 'track', 'wbr',
@@ -67,6 +123,31 @@ function applyLoopChain(loop: import('../types').IRLoop, base: string = loop.arr
   })
 }
 
+/**
+ * Wrap an array expression with the iterator shape and build the
+ * `.map()` callback parameter for `entries` / `keys` iteration.
+ * Returns the (possibly wrapped) array and the callback param string.
+ */
+function applyIterationShape(
+  node: import('../types').IRLoop,
+  arrayExpr: string,
+  indexParam: string,
+): { array: string; callbackParam: string } {
+  if (node.iterationShape === 'entries' && node.index) {
+    return {
+      array: `[...${arrayExpr}.entries()]`,
+      callbackParam: `([${node.index}, ${node.param}])`,
+    }
+  }
+  if (node.iterationShape === 'keys') {
+    return {
+      array: `[...${arrayExpr}.keys()]`,
+      callbackParam: `(${node.param})`,
+    }
+  }
+  return { array: arrayExpr, callbackParam: `(${node.param}${indexParam})` }
+}
+
 function childrenPropEntry(
   children: IRNode[],
   recurse: (n: IRNode) => string,
@@ -488,7 +569,9 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       // where the template is the only source of truth. The chain
       // mirrors `buildChainedArrayExpr` so reconcileList sees the
       // same array shape this template emits.
-      const wrappedArray = wrapExpr(applyLoopChain(node))
+      const rawChainedArray = applyLoopChain(node)
+      const { array: iterArray, callbackParam } = applyIterationShape(node, rawChainedArray, indexParam)
+      const wrappedArray = wrapExpr(iterArray)
       const iterMethod = node.method ?? 'map'
       let mapExpr: string
 
@@ -501,9 +584,9 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
         }
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
       } else if (node.mapPreamble) {
-        mapExpr = `\${${wrappedArray}.${iterMethod}((${node.param}${indexParam}) => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`
       } else {
-        mapExpr = `\${${wrappedArray}.${iterMethod}((${node.param}${indexParam}) => \`${childTemplate}\`).join('')}`
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`
       }
       // Wrap with loop boundary markers so reconciliation doesn't affect siblings
       return `<!--${loopStartMarker(node.markerId)}-->${mapExpr}<!--${loopEndMarker(node.markerId)}-->`
@@ -600,7 +683,9 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
       const indexParam = node.index ? `, ${node.index}` : ''
       // Apply sort / filter chain (#1448 Tier B) — same shape as the
       // `irToHtmlTemplate` loop case above.
-      const wrappedArray = wrapExpr(applyLoopChain(node))
+      const rawChainedArray = applyLoopChain(node)
+      const { array: iterArray, callbackParam } = applyIterationShape(node, rawChainedArray, indexParam)
+      const wrappedArray = wrapExpr(iterArray)
       const iterMethod = node.method ?? 'map'
       let mapExpr: string
       if (node.flatMapCallback) {
@@ -611,9 +696,9 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
         }
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
       } else if (node.mapPreamble) {
-        mapExpr = `\${${wrappedArray}.${iterMethod}((${node.param}${indexParam}) => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${node.mapPreamble} return \`${childTemplate}\` }).join('')}`
       } else {
-        mapExpr = `\${${wrappedArray}.${iterMethod}((${node.param}${indexParam}) => \`${childTemplate}\`).join('')}`
+        mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`
       }
       return `<!--${loopStartMarker(node.markerId)}-->${mapExpr}<!--${loopEndMarker(node.markerId)}-->`
     }
@@ -1417,8 +1502,9 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
       const chainedTemplateArray = node.sortComparator || node.filterPredicate
         ? applyLoopChain(node, node.templateArray)
         : node.templateArray
-      const arrayExpr = transformExpr(node.array, chainedTemplateArray)
-      const safeArrayExpr = arrayExpr === UNSAFE_TEMPLATE_EXPR ? '[]' : arrayExpr
+      const rawArrayExpr = transformExpr(node.array, chainedTemplateArray)
+      const safeRawArrayExpr = rawArrayExpr === UNSAFE_TEMPLATE_EXPR ? '[]' : rawArrayExpr
+      const { array: iterArrayExpr, callbackParam } = applyIterationShape(node, safeRawArrayExpr, indexParam)
       const iterMethod = node.method ?? 'map'
       let mapExpr: string
       if (node.flatMapCallback) {
@@ -1428,13 +1514,13 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
           body = body.replace(frag.placeholder, `\`${renderedIr}\``)
         }
         body = applyPropsRewrite(body, propsObjectName ?? null)
-        mapExpr = `\${${safeArrayExpr}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
+        mapExpr = `\${${iterArrayExpr}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
       } else if (node.mapPreamble) {
         const rawPreamble = node.templateMapPreamble ?? node.mapPreamble
         const preamble = applyPropsRewrite(rawPreamble, propsObjectName ?? null)
-        mapExpr = `\${${safeArrayExpr}.${iterMethod}((${node.param}${indexParam}) => { ${preamble} return \`${childTemplate}\` }).join('')}`
+        mapExpr = `\${${iterArrayExpr}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`
       } else {
-        mapExpr = `\${${safeArrayExpr}.${iterMethod}((${node.param}${indexParam}) => \`${childTemplate}\`).join('')}`
+        mapExpr = `\${${iterArrayExpr}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`
       }
       return `<!--${loopStartMarker(node.markerId)}-->${mapExpr}<!--${loopEndMarker(node.markerId)}-->`
     }

package/src/ir-to-client-js/types.ts

@@ -222,6 +222,12 @@ export interface LoopCore {
    * names as a recurring source of "forgotten variant" defects.
    */
   bindings: LoopChildBindings
+
+  /**
+   * Iteration shape from `.entries()` / `.keys()` / `.values()` chain
+   * (#1448 Tier B). Threaded from `IRLoop.iterationShape`.
+   */
+  iterationShape?: 'entries' | 'keys'
 }
 
 /**

package/src/ir-to-client-js/utils.ts

@@ -16,9 +16,10 @@ import {
   BF_LOOP_END,
   loopStartMarker,
   loopEndMarker,
+  toHTMLAttrName as toHtmlAttrName,
 } from '@barefootjs/shared'
 
-export { DATA_KEY, DATA_KEY_PREFIX, DATA_BF_PH, BF_LOOP_START, BF_LOOP_END, loopStartMarker, loopEndMarker }
+export { DATA_KEY, DATA_KEY_PREFIX, DATA_BF_PH, BF_LOOP_START, BF_LOOP_END, loopStartMarker, loopEndMarker, toHtmlAttrName }
 
 /**
  * Parameter name for the props object in generated init/template functions.
@@ -167,70 +168,8 @@ export function quotePropName(name: string): string {
   return JSON.stringify(name)
 }
 
-/**
- * SVG presentation attribute names that are written camelCase in JSX
- * (React-compatible spelling) and must be emitted as kebab-case at the
- * DOM/HTML layer.
- *
- * Why this exists: SSR template output and client-side reactive
- * `setAttribute` both flow through `toHtmlAttrName`. If they disagree on
- * the spelling, SSR emits `stroke-width="1.5"` while hydration writes
- * `setAttribute('strokeWidth', '2.5')`, leaving both attributes on the
- * DOM. The SVG renderer reads the kebab-case form, so reactive updates
- * become invisible. This map keeps both paths in sync. Surfaced by the
- * Graph/DAG Editor block (#135) where edge selection failed to thicken
- * the stroke even though `selectedEdgeId()` updated correctly.
- *
- * Listed names are SVG-only — none of them collide with HTML attributes.
- */
-const SVG_CAMEL_TO_KEBAB: Record<string, string> = {
-  // stroke
-  strokeWidth: 'stroke-width',
-  strokeLinecap: 'stroke-linecap',
-  strokeLinejoin: 'stroke-linejoin',
-  strokeDasharray: 'stroke-dasharray',
-  strokeDashoffset: 'stroke-dashoffset',
-  strokeMiterlimit: 'stroke-miterlimit',
-  strokeOpacity: 'stroke-opacity',
-  // fill
-  fillOpacity: 'fill-opacity',
-  fillRule: 'fill-rule',
-  // gradient stops
-  stopColor: 'stop-color',
-  stopOpacity: 'stop-opacity',
-  // text presentation
-  textAnchor: 'text-anchor',
-  dominantBaseline: 'dominant-baseline',
-  alignmentBaseline: 'alignment-baseline',
-  fontFamily: 'font-family',
-  fontSize: 'font-size',
-  fontWeight: 'font-weight',
-  fontStyle: 'font-style',
-  letterSpacing: 'letter-spacing',
-  wordSpacing: 'word-spacing',
-  // common presentation / interaction
-  pointerEvents: 'pointer-events',
-  vectorEffect: 'vector-effect',
-  colorInterpolation: 'color-interpolation',
-  clipPath: 'clip-path',
-  clipRule: 'clip-rule',
-  // marker references
-  markerStart: 'marker-start',
-  markerMid: 'marker-mid',
-  markerEnd: 'marker-end',
-}
-
-/**
- * Convert JSX attribute name to HTML attribute name.
- * Handles React-style naming conventions (e.g., className → class) and
- * SVG presentation attributes (e.g., strokeWidth → stroke-width).
- */
-export function toHtmlAttrName(jsxAttrName: string): string {
-  if (jsxAttrName === 'className') return 'class'
-  const svgKebab = SVG_CAMEL_TO_KEBAB[jsxAttrName]
-  if (svgKebab !== undefined) return svgKebab
-  return jsxAttrName
-}
+// toHtmlAttrName is now re-exported from @barefootjs/shared (classifyDOMProp's
+// toHTMLAttrName), keeping the same public name for downstream consumers.
 
 /**
  * Wrap arrow function handler in block to prevent accidental return false.

package/src/jsx-to-ir.ts

@@ -2013,15 +2013,20 @@ function transformConditionalBranch(
     effect: 'pure',
     freeRefs: resolveFreeRefs(node, makeBindingEnv(ctx)),
   }
+  const callsReactive = exprCallsReactiveGetters(node, ctx)
+  const hasCalls = exprHasFunctionCalls(node)
+  const reactive = isReactiveExpression(exprText, ctx, node) || isReactiveOrigin(branchOrigin)
+  const needsSlot = reactive || callsReactive
+  const slotId = needsSlot ? generateSlotId(ctx) : null
   return {
     type: 'expression',
     expr: exprText,
     templateExpr: rewriteBarePropRefs(exprText, node, ctx),
     typeInfo: inferExpressionType(node, ctx),
-    reactive: isReactiveExpression(exprText, ctx, node) || isReactiveOrigin(branchOrigin),
-    slotId: null,
-    callsReactiveGetters: exprCallsReactiveGetters(node, ctx) || undefined,
-    hasFunctionCalls: exprHasFunctionCalls(node) || undefined,
+    reactive,
+    slotId,
+    callsReactiveGetters: callsReactive || undefined,
+    hasFunctionCalls: hasCalls || undefined,
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
     origin: branchOrigin,
   }
@@ -2077,6 +2082,23 @@ function isSortCall(node: ts.Expression): { array: ts.Expression; callback: ts.E
   }
 }
 
+/**
+ * Check if a node is an `.entries()`, `.keys()`, or `.values()` call
+ * (zero-arg, property-access form). Returns the underlying array expression
+ * and the iteration shape so `transformMapCall` can strip the iterator
+ * method and record it on the IRLoop.
+ */
+function isIteratorShapeCall(
+  node: ts.Expression,
+): { array: ts.LeftHandSideExpression; shape: 'entries' | 'keys' | 'values' } | null {
+  if (!ts.isCallExpression(node)) return null
+  if (!ts.isPropertyAccessExpression(node.expression)) return null
+  if (node.arguments.length !== 0) return null
+  const name = node.expression.name.text
+  if (name !== 'entries' && name !== 'keys' && name !== 'values') return null
+  return { array: node.expression.expression, shape: name }
+}
+
 type SortExtractionResult = {
   result: SortComparator | null
   unsupportedReason?: string
@@ -2672,6 +2694,7 @@ function transformMapCall(
   // 2. filter().map()
   // 3. filter().sort().map()  (outermost = sort, inner = filter)
   // 4. sort().filter().map()  (outermost = filter, inner = sort)
+  // 5. entries().map() / keys().map() / values().map()
 
   let array: string = ''
   let templateArray: string | undefined
@@ -2686,6 +2709,7 @@ function transformMapCall(
   let mapPreamble: string | undefined
   let templateMapPreamble: string | undefined
   let typedMapPreamble: string | undefined
+  let iterationShape: 'entries' | 'keys' | undefined
 
   // Helper to set both array and templateArray
   const setArray = (node: ts.Expression) => {
@@ -2694,8 +2718,26 @@ function transformMapCall(
     arrayExpr = node
   }
 
-  const filterInfo = isFilterCall(mapSource)
-  const sortInfo = isSortCall(mapSource)
+  // Detect `.entries()`, `.keys()`, `.values()` as the outermost wrapper
+  // on the map source. Strip the iterator method and record the shape so
+  // 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
+  const iteratorInfo = isIteratorShapeCall(mapSource)
+  if (iteratorInfo) {
+    chainSource = iteratorInfo.array
+    if (iteratorInfo.shape === 'entries') {
+      iterationShape = 'entries'
+    } else if (iteratorInfo.shape === 'keys') {
+      iterationShape = 'keys'
+    }
+    // 'values' is a no-op — same as plain .map()
+  }
+
+  const filterInfo = isFilterCall(chainSource)
+  const sortInfo = isSortCall(chainSource)
 
   if (sortInfo) {
     // Outermost is sort: could be sort().map() or filter().sort().map()
@@ -2810,8 +2852,8 @@ function transformMapCall(
       }
     }
   } else {
-    array = ctx.getJS(mapSource)
-    arrayExpr = mapSource
+    array = ctx.getJS(chainSource)
+    arrayExpr = chainSource
   }
 
   // Get callback function
@@ -2839,18 +2881,50 @@ function transformMapCall(
       // residual-object / `.slice(n)` accessor at each reference. Only
       // computed property keys remain unsupported — those raise `BF025`
       // and the emitter falls back to the #950 body-entry unwrap.
-      const bindingResult = extractLoopParamBindings(firstParam.name)
-      if (bindingResult && !Array.isArray(bindingResult)) {
-        ctx.analyzer.errors.push(
-          createError(ErrorCodes.UNSUPPORTED_DESTRUCTURE_REST,
-            getSourceLocation(firstParam, ctx.sourceFile, ctx.filePath),
-          )
+      // `.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)) {
+        const elements = firstParam.name.elements.filter(
+          el => !ts.isOmittedExpression(el),
         )
-      } else if (Array.isArray(bindingResult)) {
-        paramBindings = bindingResult
+        if (elements.length === 2 &&
+            ts.isBindingElement(elements[0]) && ts.isIdentifier(elements[0].name) &&
+            ts.isBindingElement(elements[1]) && ts.isIdentifier(elements[1].name)) {
+          index = elements[0].name.text
+          param = elements[1].name.text
+          // Don't populate paramBindings — the destructure is fully
+          // resolved into index + param by the iteration shape.
+        } else {
+          // Non-2-element destructure with .entries() — fall through to
+          // standard destructure handling (will trigger BF104 on
+          // template adapters).
+          const bindingResult = extractLoopParamBindings(firstParam.name)
+          if (bindingResult && !Array.isArray(bindingResult)) {
+            ctx.analyzer.errors.push(
+              createError(ErrorCodes.UNSUPPORTED_DESTRUCTURE_REST,
+                getSourceLocation(firstParam, ctx.sourceFile, ctx.filePath),
+              )
+            )
+          } else if (Array.isArray(bindingResult)) {
+            paramBindings = bindingResult
+          }
+        }
+      } else {
+        const bindingResult = extractLoopParamBindings(firstParam.name)
+        if (bindingResult && !Array.isArray(bindingResult)) {
+          ctx.analyzer.errors.push(
+            createError(ErrorCodes.UNSUPPORTED_DESTRUCTURE_REST,
+              getSourceLocation(firstParam, ctx.sourceFile, ctx.filePath),
+            )
+          )
+        } else if (Array.isArray(bindingResult)) {
+          paramBindings = bindingResult
+        }
       }
     }
-    if (callback.parameters.length > 1) {
+    if (callback.parameters.length > 1 && iterationShape !== 'entries') {
       const secondParam = callback.parameters[1]
       index = secondParam.name.getText(ctx.sourceFile)
       if (secondParam.type) {
@@ -3065,6 +3139,7 @@ function transformMapCall(
     filterPredicate,
     sortComparator,
     chainOrder,
+    iterationShape,
     clientOnly: isClientOnly || undefined,
     mapPreamble,
     templateMapPreamble,

package/src/prop-rewrite.ts

@@ -8,6 +8,7 @@
 
 import ts from 'typescript'
 import { PROPS_PARAM } from './ir-to-client-js/utils'
+import { createTemplateAwareStringProtector } from './ir-to-client-js/html-template'
 
 /**
  * Walk an AST node for destructured-prop value references and add
@@ -47,7 +48,9 @@ export function applyRegexPropRefRewrite(
   text: string,
   propRefs: Iterable<string>,
 ): string {
-  let result = text
+  const { protect, restore } = createTemplateAwareStringProtector()
+  let result = protect(text)
+
   for (const propName of propRefs) {
     const pattern = new RegExp(`(?<!${PROPS_PARAM}\\.)(?<!['"\\w.-])\\b${propName}\\b(?![a-zA-Z0-9_$])`, 'g')
     result = result.replace(pattern, (match, offset, str) => {
@@ -60,7 +63,8 @@ export function applyRegexPropRefRewrite(
       return `${PROPS_PARAM}.${propName}`
     })
   }
-  return result
+
+  return restore(result)
 }
 
 /**

package/src/types.ts

@@ -496,6 +496,27 @@ export interface IRLoop {
    */
   chainOrder?: 'filter-sort' | 'sort-filter'
 
+  /**
+   * Pre-`.map()` iteration shape (#1448 Tier B).
+   *
+   * When the user writes `arr.entries().map(([i, v]) => ...)`,
+   * `arr.keys().map(i => ...)`, or `arr.values().map(v => ...)`,
+   * the chain-detection in `transformMapCall` strips the iterator
+   * method and records the shape here so adapters can emit the
+   * right loop variable bindings:
+   *
+   *   - `'entries'` → both index and value are bound
+   *     (Go: `$i, $v`; Mojo: `$i` + `$v = $arr->[$i]`)
+   *   - `'keys'` → only the index is bound
+   *     (Go: `$i, $_ :=`; Mojo: `$i` with no per-item lookup)
+   *   - `undefined` / `'values'` → standard iteration (value only)
+   *
+   * The chain detection also synthesises proper `param` / `index`
+   * from the `.entries()` destructure pattern so the BF104
+   * destructure-param refusal doesn't fire.
+   */
+  iterationShape?: 'entries' | 'keys'
+
   /**
    * When true, loop should be evaluated on client side only.
    * SSR adapters should skip rendering and output placeholder markers.