@barefootjs/jsx 0.18.4 → 0.18.5

package/src/expression-parser.ts

@@ -25,7 +25,21 @@ export type ParsedExpr =
   // canonical form in `value`.
   | { kind: 'literal'; value: string | number | boolean | null; literalType: 'string' | 'number' | 'boolean' | 'null'; raw?: string }
   | { kind: 'call'; callee: ParsedExpr; args: ParsedExpr[] }
-  | { kind: 'member'; object: ParsedExpr; property: string; computed: boolean }
+  // `optional` is true for a `?.`-written access (`user?.name`,
+  // `arr?.[0]`) — the ONE hop that was actually optional-chained in JS
+  // source; a plain `.`/`[]` access is `false`. Adapters whose member
+  // lowering is already null-safe by construction (e.g. Jinja's `[]`
+  // subscript swallows a `None` receiver, Blade's `data_get` helper)
+  // ignore this field entirely; Go and ERB (whose native `.` access
+  // panics/raises on a nil/undefined receiver) route an `optional: true`
+  // access through a defensive form (`bf_get`, Ruby `&.`) instead. NOTE:
+  // this does NOT reproduce JS's whole-chain short-circuit for a
+  // MULTI-hop chain (`a?.b.c` also guards `.c` in JS once `a` is
+  // nullish) — only the single hop written with `?.` is marked; a
+  // following plain `.c` on a possibly-nullish `a?.b` is a known,
+  // untracked limitation on Go/ERB (not exercised by the current
+  // `optional-chaining-prop` fixture, which is single-hop only).
+  | { kind: 'member'; object: ParsedExpr; property: string; computed: boolean; optional: boolean }
   // Element access with a NON-literal index (`selected()[index]`,
   // `rows[i + 1]`). A literal-index access (`arr[0]`, `obj['key']`)
   // stays a `member` (computed) since the key is statically known and
@@ -88,11 +102,14 @@ export type ParsedExpr =
         | 'toLowerCase'
         | 'toUpperCase'
         | 'trim'
+        | 'trimStart'
+        | 'trimEnd'
         | 'toFixed'
         | 'split'
         | 'startsWith'
         | 'endsWith'
         | 'replace'
+        | 'replaceAll'
         | 'repeat'
         | 'padStart'
         | 'padEnd'
@@ -345,18 +362,17 @@ const UNSUPPORTED_METHODS = new Set([
   // `startsWith` / `endsWith` are no longer here — both lower via the
   // `array-method` IR + `bf_starts_with` / `bf_ends_with` (Go) and
   // `bf->starts_with` / `bf->ends_with` (Mojo). See #1448 Tier B.
-  // `replace` is no longer here — the string-pattern form lowers via
-  // the `array-method` IR + `bf_replace` (Go) / `bf->replace` (Mojo);
-  // the regex-pattern form is refused at the parse arm below (it would
-  // need the per-adapter regex-flavour decision). `replaceAll` stays
-  // refused. See #1448 Tier B.
+  // `replace` / `replaceAll` are no longer here — the string-pattern
+  // form of each lowers via the `array-method` IR + `bf_replace` /
+  // `bf_replace_all` (Go) / `bf->replace` / `bf->replace_all` (Mojo);
+  // the regex-pattern form of EITHER is refused at the parse arm below
+  // (it would need the per-adapter regex-flavour decision).
   // `repeat` is no longer here — `String.prototype.repeat(n)` lowers via
   // the `array-method` IR + `bf_repeat` (Go) / `bf->repeat` (Mojo).
   // See #1448 Tier B.
   // `padStart` / `padEnd` are no longer here — both lower via the
   // `array-method` IR + `bf_pad_start` / `bf_pad_end` (Go) and
   // `bf->pad_start` / `bf->pad_end` (Mojo). See #1448 Tier B.
-  'replaceAll',
   'charAt', 'charCodeAt', 'codePointAt', 'normalize',
   'substring', 'substr', 'match', 'matchAll', 'search',
 ])
@@ -882,6 +898,16 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       if (callee.property === 'trim') {
         return { kind: 'array-method', method: 'trim', object: callee.object, args }
       }
+      // `.trimStart()` / `.trimEnd()` — the one-sided siblings of
+      // `.trim()` (#2183 follow-up). No array equivalent exists, so
+      // there's no receiver-type ambiguity to resolve (unlike `.slice`);
+      // each is a dedicated `array-method` variant (matching the
+      // `padStart`/`padEnd` precedent — separate members, not a shared
+      // member with a `side` flag) lowering to its own runtime helper
+      // per adapter, not `.trim()` with a flag.
+      if (callee.property === 'trimStart' || callee.property === 'trimEnd') {
+        return { kind: 'array-method', method: callee.property, object: callee.object, args }
+      }
       // `.toFixed(digits?)` — Number → fixed-decimal string. The digit
       // count (default 0) travels as the single arg; all adapters route
       // through a `to_fixed` runtime helper (Perl) / `fmt.Sprintf` (Go)
@@ -954,19 +980,25 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       // refused: `isSupported` maps a regex-pattern `.replace` to the
       // deferred-form BF101 reason — the Perl `s///` vs Go
       // `regexp.ReplaceAllString` flavour gap is the open design
-      // question in #1448. `replaceAll` stays refused entirely.
+      // question in #1448. `.replaceAll(pattern, replacement)` shares
+      // this arm (#2182 follow-up): same arity/regex/object-literal
+      // gates, only the `method` tag and its runtime helper differ —
+      // `bf_replace_all` (Go, `strings.ReplaceAll`) / `bf->replace_all`
+      // (Mojo) replace EVERY occurrence, where `.replace`'s helpers
+      // replace only the first.
       //
       // Full JS arity: a third+ argument is ignored (the adapter reads
       // only the pattern + replacement). The one- and zero-argument
       // forms are refused: JS coerces the missing replacement (and
       // pattern) to the literal string "undefined", a degenerate result
       // (mirrors the `.includes()` / `.startsWith()` zero-arg refusal).
-      if (callee.property === 'replace') {
+      if (callee.property === 'replace' || callee.property === 'replaceAll') {
+        const method = callee.property
         if (args.length < 2) {
           return {
             kind: 'unsupported',
             raw,
-            reason: `\`.replace(${args.length === 0 ? '' : 'pattern'})\` needs both a pattern and a replacement — JS coerces the missing argument to the string "undefined", a degenerate result. Pass both arguments, or pre-compute the value before the template.`,
+            reason: `\`.${method}(${args.length === 0 ? '' : 'pattern'})\` needs both a pattern and a replacement — JS coerces the missing argument to the string "undefined", a degenerate result. Pass both arguments, or pre-compute the value before the template.`,
           }
         }
         // A regex-literal pattern is the deferred form (the Perl `s///`
@@ -980,7 +1012,7 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
         // any template use with the deferred-form reason.
         const patternNode = node.arguments[0]
         if (patternNode && ts.isRegularExpressionLiteral(patternNode)) {
-          return { kind: 'array-method', method: 'replace', object: callee.object, args }
+          return { kind: 'array-method', method, object: callee.object, args }
         }
         // Treat an object-literal argument like `unsupported` — a `.replace`
         // with an object pattern/replacement isn't lowerable, same as before
@@ -995,7 +1027,7 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
           const reason = badArg.kind === 'unsupported' ? badArg.reason : 'Unsupported syntax: ObjectLiteralExpression'
           return { kind: 'unsupported', raw, reason }
         }
-        return { kind: 'array-method', method: 'replace', object: callee.object, args }
+        return { kind: 'array-method', method, object: callee.object, args }
       }
       // `.repeat(n)` — string → string (the receiver concatenated `n`
       // times). Go uses `bf_repeat` (`strings.Repeat`, clamping a
@@ -1072,7 +1104,7 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
     const property = node.name.text
 
     // Return as normal member - filter.length is handled in adapter
-    return { kind: 'member', object, property, computed: false }
+    return { kind: 'member', object, property, computed: false, optional: !!node.questionDotToken }
   }
 
   // Element access: items[0], obj['key']
@@ -1088,10 +1120,10 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
     }
     // For simple number/string access, store as property
     if (ts.isNumericLiteral(argNode)) {
-      return { kind: 'member', object, property: argNode.text, computed: true }
+      return { kind: 'member', object, property: argNode.text, computed: true, optional: !!node.questionDotToken }
     }
     if (ts.isStringLiteral(argNode)) {
-      return { kind: 'member', object, property: argNode.text, computed: true }
+      return { kind: 'member', object, property: argNode.text, computed: true, optional: !!node.questionDotToken }
     }
     // Variable / expression index (`selected()[index]`, `rows[i + 1]`):
     // carry the index as its own ParsedExpr so the adapter can lower it
@@ -2063,7 +2095,7 @@ function substituteDestructuredFields(
         // one-hop chain identical to the pre-#1530 shape.
         let node: ParsedExpr = { kind: 'identifier', name: syntheticParam }
         for (const segment of entry.path) {
-          node = { kind: 'member', object: node, property: segment, computed: false }
+          node = { kind: 'member', object: node, property: segment, computed: false, optional: false }
         }
         // Default value (#1531): wrap the accessor in `?? <default>` so
         // a missing field falls back to the user-supplied literal /
@@ -2088,9 +2120,10 @@ function substituteDestructuredFields(
             object: { kind: 'identifier', name: syntheticParam },
             property: e.property,
             computed: false,
+            optional: e.optional,
           }
         }
-        return { kind: 'member', object: walk(e.object), property: e.property, computed: e.computed }
+        return { kind: 'member', object: walk(e.object), property: e.property, computed: e.computed, optional: e.optional }
       case 'index-access':
         return { kind: 'index-access', object: walk(e.object), index: walk(e.index) }
       case 'binary':
@@ -2236,15 +2269,16 @@ function checkSupport(expr: ParsedExpr): SupportResult {
     }
 
     case 'array-method': {
-      // A regex-pattern `.replace` is carried structurally (a `regex` first
-      // arg) but is the deferred form (#1448) — no template language lowers it.
-      // Refuse with the dedicated reason rather than the generic standalone-regex
-      // message, preserving the diagnostic the parser used to emit directly.
-      if (expr.method === 'replace' && expr.args[0]?.kind === 'regex') {
+      // A regex-pattern `.replace` / `.replaceAll` is carried structurally
+      // (a `regex` first arg) but is the deferred form (#1448) — no
+      // template language lowers it. Refuse with the dedicated reason
+      // rather than the generic standalone-regex message, preserving the
+      // diagnostic the parser used to emit directly.
+      if ((expr.method === 'replace' || expr.method === 'replaceAll') && expr.args[0]?.kind === 'regex') {
         return {
           supported: false,
           reason:
-            'String.prototype.replace supports only a string pattern + string replacement (the regex form is deferred); use a string pattern or wrap the expression in /* @client */',
+            `String.prototype.${expr.method} supports only a string pattern + string replacement (the regex form is deferred); use a string pattern or wrap the expression in /* @client */`,
         }
       }
       const objSupport = checkSupport(expr.object)
@@ -2893,7 +2927,7 @@ function inlineBinding(
       case 'call':
         return { kind: 'call', callee: walk(e.callee, enclosing), args: e.args.map(a => walk(a, enclosing)) }
       case 'member':
-        return { kind: 'member', object: walk(e.object, enclosing), property: e.property, computed: e.computed }
+        return { kind: 'member', object: walk(e.object, enclosing), property: e.property, computed: e.computed, optional: e.optional }
       case 'index-access':
         return { kind: 'index-access', object: walk(e.object, enclosing), index: walk(e.index, enclosing) }
       case 'binary':
@@ -3281,7 +3315,7 @@ export function materializeGetterCalls(expr: ParsedExpr, names: ReadonlySet<stri
         alternate: rw(expr.alternate),
       }
     case 'member':
-      return { kind: 'member', object: rw(expr.object), property: expr.property, computed: expr.computed }
+      return { kind: 'member', object: rw(expr.object), property: expr.property, computed: expr.computed, optional: expr.optional }
     case 'index-access':
       return { kind: 'index-access', object: rw(expr.object), index: rw(expr.index) }
     case 'template-literal':

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

@@ -390,6 +390,7 @@ export function collectInnerLoops(
           bodyIsMultiRoot: n.bodyIsMultiRoot,
           bodyIsItemConditional: n.bodyIsItemConditional,
           iterationShape: n.iterationShape,
+          objectIteration: n.objectIteration,
           containerSlotId: scope.parentSlotId,
           template,
           mapPreamble: n.mapPreamble,
@@ -743,6 +744,7 @@ export function collectElements(
         bodyIsMultiRoot: l.bodyIsMultiRoot,
         bodyIsItemConditional: l.bodyIsItemConditional,
         iterationShape: l.iterationShape,
+        objectIteration: l.objectIteration,
         template,
         staticItemTemplate,
         skeletonTemplate,
@@ -1096,6 +1098,7 @@ function collectBranchLoops(
         bodyIsMultiRoot: n.bodyIsMultiRoot,
         bodyIsItemConditional: n.bodyIsItemConditional,
         iterationShape: n.iterationShape,
+        objectIteration: n.objectIteration,
         template: childTemplate,
         containerSlotId: containerSlot,
         mapPreamble: n.mapPreamble ?? null,

package/src/ir-to-client-js/control-flow/plan/build-event-delegation.ts

@@ -34,6 +34,7 @@ export function buildDynamicLoopDelegationPlan(
       param: elem.param,
       paramBindings: elem.paramBindings,
       key: elem.key,
+      index: elem.index,
       mapPreamble: elem.mapPreamble ?? null,
     }),
   }
@@ -58,6 +59,7 @@ export function buildBranchLoopDelegationPlan(
       param: loop.param,
       paramBindings: loop.paramBindings,
       key: loop.key,
+      index: loop.index,
       mapPreamble: loop.mapPreamble ?? null,
     }),
   }
@@ -86,6 +88,7 @@ export function buildStaticArrayDelegationPlan(
       param: elem.param,
       mapPreamble: elem.mapPreamble ?? null,
       offset: elem.offset ?? null,
+      indexParam: elem.index ?? null,
     },
   }
 }
@@ -99,6 +102,7 @@ function buildKeyedOrIndexLookup(args: {
   param: string
   paramBindings: TopLevelLoop['paramBindings']
   key: string | null
+  index: string | null
   mapPreamble: string | null
 }): ItemLookup {
   const hasBindings = (args.paramBindings?.length ?? 0) > 0
@@ -116,6 +120,7 @@ function buildKeyedOrIndexLookup(args: {
       keyWithItem,
       mapPreamble: args.mapPreamble,
       hasBindings,
+      indexParam: args.index,
     }
   }
   return {
@@ -124,6 +129,7 @@ function buildKeyedOrIndexLookup(args: {
     param: args.param,
     mapPreamble: args.mapPreamble,
     hasBindings,
+    indexParam: args.index,
   }
 }
 

package/src/ir-to-client-js/control-flow/plan/event-delegation.ts

@@ -51,6 +51,12 @@ export interface KeyedItemLookup {
   arrayExpr: string
   /** Loop param identifier (or destructure pattern text — used as receiver name only). */
   param: string
+  /**
+   * Loop index param name (e.g. `i` from `.map((item, i) => ...)`), or `null`.
+   * When a delegated handler closes over it, the stringifier re-derives the
+   * index at dispatch time and binds it so the reference resolves (#2189).
+   */
+  indexParam: string | null
   /** Destructured-binding metadata. Determines TDZ-safe `__bfLoopItem` shape (#951). */
   paramBindings: TopLevelLoop['paramBindings']
   /**
@@ -72,6 +78,8 @@ export interface DynamicIndexItemLookup {
   param: string
   mapPreamble: string | null
   hasBindings: boolean
+  /** Loop index param name — see `KeyedItemLookup.indexParam` (#2189). */
+  indexParam: string | null
 }
 
 export interface StaticIndexItemLookup {
@@ -79,6 +87,8 @@ export interface StaticIndexItemLookup {
   arrayExpr: string
   param: string
   mapPreamble: string | null
+  /** Loop index param name — see `KeyedItemLookup.indexParam` (#2189). */
+  indexParam: string | null
   /**
    * Offset of the loop's items past its preceding container siblings. Its
    * terms are subtracted from the DOM child index to recover the array index,

package/src/ir-to-client-js/control-flow/stringify/event-delegation.ts

@@ -33,6 +33,7 @@
  */
 
 import { toDomEventName, varSlotId, substituteLoopBindings, buildLoopChildIndexSubtraction, DATA_KEY, keyAttrName } from '../../utils.ts'
+import { extractFreeIdentifiersFromText } from '../../csr-substitute.ts'
 import type {
   EventDelegationPlan,
   KeyedItemLookup,
@@ -60,6 +61,19 @@ function withTurn(call: string, componentName: string | undefined, childSlotId:
   return `beginTurn(${id}); try { ${call} } finally { endTurn() }`
 }
 
+/**
+ * Bind the loop index under the user's param name for a delegated handler that
+ * closes over it (#2189). Returns `null` when there is no index param, the
+ * handler doesn't reference it (so unaffected loops keep byte-for-byte output),
+ * or the name already equals the in-scope index var (a self-alias). Uses AST
+ * free identifiers, not a token match, so `item.id` (property) doesn't count.
+ */
+function indexBindingLine(handler: string, indexParam: string | null, indexExpr: string): string | null {
+  if (!indexParam || indexParam === indexExpr) return null
+  if (!extractFreeIdentifiersFromText(handler).has(indexParam)) return null
+  return `const ${indexParam} = ${indexExpr}`
+}
+
 export function stringifyEventDelegation(lines: string[], plan: EventDelegationPlan): void {
   const { containerVar, events, itemLookup, profileComponentName } = plan
   const eventsByName = new Map<string, LoopChildEvent[]>()
@@ -112,10 +126,11 @@ function emitKeyedLookup(
   handlerCall: string,
   lookup: KeyedItemLookup,
 ): void {
-  const { arrayExpr, param, keyWithItem, mapPreamble, hasBindings } = lookup
+  const { arrayExpr, param, keyWithItem, mapPreamble, hasBindings, indexParam } = lookup
 
   if (ev.nestedLoops.length === 0) {
     // Single-level keyed lookup.
+    const idxLine = indexBindingLine(ev.handler, indexParam, `${arrayExpr}.findIndex(item => String(${keyWithItem}) === key)`)
     ls.push(`      const li = ${varSlotId(ev.childSlotId)}El.closest('[${DATA_KEY}]')`)
     ls.push(`      if (li) {`)
     ls.push(`        const key = li.getAttribute('${DATA_KEY}')`)
@@ -125,12 +140,14 @@ function emitKeyedLookup(
       ls.push(`        if (__bfLoopItem) {`)
       ls.push(`          const ${param} = __bfLoopItem`)
       if (mapPreamble) ls.push(`          ${mapPreamble}`)
+      if (idxLine) ls.push(`          ${idxLine}`)
       ls.push(`          ${handlerCall}`)
       ls.push(`        }`)
     } else {
       ls.push(`        const ${param} = ${arrayExpr}.find(item => String(${keyWithItem}) === key)`)
       if (mapPreamble) ls.push(`        ${mapPreamble}`)
-      ls.push(`        if (${param}) ${handlerCall}`)
+      if (idxLine) ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`)
+      else ls.push(`        if (${param}) ${handlerCall}`)
     }
     ls.push(`      }`)
     return
@@ -164,7 +181,9 @@ function emitKeyedLookup(
   const outerGuard = hasBindings ? '__bfLoopItem' : param
   const allParams = [outerGuard, ...ev.nestedLoops.map(n => n.param)]
   if (mapPreamble) ls.push(`      ${mapPreamble}`)
-  ls.push(`      if (${allParams.join(' && ')}) ${handlerCall}`)
+  const idxLine = indexBindingLine(ev.handler, indexParam, `${arrayExpr}.findIndex(item => String(${keyWithItem}) === outerKey)`)
+  if (idxLine) ls.push(`      if (${allParams.join(' && ')}) { ${idxLine}; ${handlerCall} }`)
+  else ls.push(`      if (${allParams.join(' && ')}) ${handlerCall}`)
 }
 
 function emitDynamicIndexLookup(
@@ -173,7 +192,8 @@ function emitDynamicIndexLookup(
   handlerCall: string,
   lookup: DynamicIndexItemLookup,
 ): void {
-  const { arrayExpr, param, mapPreamble, hasBindings } = lookup
+  const { arrayExpr, param, mapPreamble, hasBindings, indexParam } = lookup
+  const idxLine = indexBindingLine(ev.handler, indexParam, 'idx')
   ls.push(`      const li = ${varSlotId(ev.childSlotId)}El.closest('li, [bf-i]')`)
   ls.push(`      if (li && li.parentElement) {`)
   ls.push(`        const idx = Array.from(li.parentElement.children).indexOf(li)`)
@@ -182,12 +202,14 @@ function emitDynamicIndexLookup(
     ls.push(`        if (__bfLoopItem) {`)
     ls.push(`          const ${param} = __bfLoopItem`)
     if (mapPreamble) ls.push(`          ${mapPreamble}`)
+    if (idxLine) ls.push(`          ${idxLine}`)
     ls.push(`          ${handlerCall}`)
     ls.push(`        }`)
   } else {
     ls.push(`        const ${param} = ${arrayExpr}[idx]`)
     if (mapPreamble) ls.push(`        ${mapPreamble}`)
-    ls.push(`        if (${param}) ${handlerCall}`)
+    if (idxLine) ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`)
+    else ls.push(`        if (${param}) ${handlerCall}`)
   }
   ls.push(`      }`)
 }
@@ -199,7 +221,8 @@ function emitStaticIndexLookup(
   lookup: StaticIndexItemLookup,
   containerVar: string,
 ): void {
-  const { arrayExpr, param, mapPreamble, offset } = lookup
+  const { arrayExpr, param, mapPreamble, offset, indexParam } = lookup
+  const idxLine = indexBindingLine(ev.handler, indexParam, '__idx')
   ls.push(`      let __el = ${varSlotId(ev.childSlotId)}El`)
   ls.push(`      while (__el.parentElement && __el.parentElement !== ${containerVar}) __el = __el.parentElement`)
   ls.push(`      if (__el.parentElement === ${containerVar}) {`)
@@ -207,6 +230,7 @@ function emitStaticIndexLookup(
   ls.push(`        const __idx = Array.from(${containerVar}.children).indexOf(__el)${idxOffset}`)
   ls.push(`        const ${param} = ${arrayExpr}[__idx]`)
   if (mapPreamble) ls.push(`        ${mapPreamble}`)
-  ls.push(`        if (${param}) ${handlerCall}`)
+  if (idxLine) ls.push(`        if (${param}) { ${idxLine}; ${handlerCall} }`)
+  else ls.push(`        if (${param}) ${handlerCall}`)
   ls.push(`      }`)
 }

package/src/ir-to-client-js/csr-substitute.ts

@@ -323,7 +323,7 @@ export function applyPropsRewrite(text: string, propsObjectName: string | null):
   return text.replace(new RegExp(`\\b${propsObjectName}\\.`, 'g'), `${PROPS_PARAM}.`)
 }
 
-function extractFreeIdentifiersFromText(text: string): Set<string> {
+export function extractFreeIdentifiersFromText(text: string): Set<string> {
   if (!text || text.trim().length === 0) return new Set()
   const sf = ts.createSourceFile(
     '__free_ids__.ts',

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

@@ -10,7 +10,7 @@ import { nameForRegistryRef } from './component-scope.ts'
 import { assertNever } from './walker.ts'
 import { buildSignalMemoEnv, csrSubstitute, applyPropsRewrite, type CsrEnv } from './csr-substitute.ts'
 import type { ClientJsContext } from './types.ts'
-import { BF_PARENT_SCOPE_PLACEHOLDER, BF_SCOPE } from '@barefootjs/shared'
+import { BF_PARENT_SCOPE_PLACEHOLDER, BF_SCOPE, escapeHtml } from '@barefootjs/shared'
 import { buildLoopChainExpr } from '../loop-chain.ts'
 
 /**
@@ -145,6 +145,42 @@ function applyIterationShape(
       callbackParam: `(${node.param})`,
     }
   }
+  // `objectIteration` (#2168 object-entries-map): reconstruct the STATIC
+  // `Object.entries/keys/values(x)` call the compiler stripped at IR-build
+  // time (`isObjectIteratorCall`, `jsx-to-ir.ts`) — `arrayExpr` here is just
+  // `x` (the plain object), so the client, unlike a template adapter,
+  // re-wraps it in real JS to get the actual entries/keys/values array
+  // (this runs in a real JS engine, so no per-language lowering is needed).
+  //
+  // Unlike the array `iterationShape` case, the 'entries' ARRAY wrap does
+  // NOT require `node.index` — that field is only populated for a CLEAN
+  // 2-identifier destructure (`([word, n]) => …`); an elided/nested
+  // pattern (`([, cfg]) => …`) falls through to the generic `paramBindings`
+  // machinery instead (`node.param` stays the raw destructure TEXT, e.g.
+  // `"[, cfg]"`, which is already a syntactically valid callback param that
+  // correctly destructures a `[key, value]` pair — see the trailing
+  // fallback below). Only the ARRAY needs wrapping in that case; the
+  // callback param is unaffected either way.
+  if (node.objectIteration === 'entries') {
+    return {
+      array: `Object.entries(${arrayExpr})`,
+      callbackParam: node.index
+        ? `([${node.index}, ${node.param}])`
+        : `(${node.param}${indexParam})`,
+    }
+  }
+  if (node.objectIteration === 'keys') {
+    return {
+      array: `Object.keys(${arrayExpr})`,
+      callbackParam: `(${node.param})`,
+    }
+  }
+  if (node.objectIteration === 'values') {
+    return {
+      array: `Object.values(${arrayExpr})`,
+      callbackParam: `(${node.param})`,
+    }
+  }
   return { array: arrayExpr, callbackParam: `(${node.param}${indexParam})` }
 }
 
@@ -313,7 +349,7 @@ function renderTemplateAttrPart(
     case 'boolean-attr':
       return attrName
     case 'literal':
-      return `${attrName}="${v.value}"`
+      return `${attrName}="${escapeHtml(v.value)}"`
     case 'expression': {
       const valExpr = wrap(v.expr)
       return templateAttrExpr(attrName, valExpr, v.presenceOrUndefined)
@@ -550,7 +586,9 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -757,7 +795,7 @@ export function buildLoopSkeletonTemplate(node: IRNode, safe: LoopSkeletonSafeSl
         const v = a.value
         switch (v.kind) {
           case 'literal':
-            attrParts.push(`${toHtmlAttrName(a.name)}="${v.value}"`)
+            attrParts.push(`${toHtmlAttrName(a.name)}="${escapeHtml(v.value)}"`)
             break
           case 'boolean-attr':
             attrParts.push(toHtmlAttrName(a.name))
@@ -796,7 +834,9 @@ export function buildLoopSkeletonTemplate(node: IRNode, safe: LoopSkeletonSafeSl
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -870,7 +910,9 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -1228,7 +1270,7 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
                 return templateAttrExpr(keyName, transformExpr(tmplStr))
               }
               case 'literal':
-                return `${keyName}="${v.value}"`
+                return `${keyName}="${escapeHtml(v.value)}"`
               default:
                 return ''
             }
@@ -1238,7 +1280,7 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
             case 'boolean-attr':
               return attrName
             case 'literal':
-              return `${attrName}="${v.value}"`
+              return `${attrName}="${escapeHtml(v.value)}"`
             case 'expression':
               return templateAttrExpr(attrName, transformExpr(v.expr, v.templateExpr), v.presenceOrUndefined)
             case 'template': {
@@ -1269,7 +1311,9 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
@@ -1806,7 +1850,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
             case 'boolean-attr':
               return attrName
             case 'literal':
-              return `${attrName}="${v.value}"`
+              return `${attrName}="${escapeHtml(v.value)}"`
             case 'expression':
               return templateAttrExpr(attrName, transformExpr(v.expr, v.templateExpr), v.presenceOrUndefined)
             case 'template': {
@@ -1837,7 +1881,9 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
     }
 
     case 'text':
-      return node.value
+      // IRText carries the entity-DECODED value; this string is parsed
+      // as HTML (template.innerHTML), so re-escape for the HTML parser.
+      return escapeHtml(node.value)
 
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''

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

@@ -283,6 +283,16 @@ export interface LoopCore {
    * (#1448 Tier B). Threaded from `IRLoop.iterationShape`.
    */
   iterationShape?: 'entries' | 'keys'
+
+  /**
+   * Object iteration shape from the STATIC `Object.entries(x)` /
+   * `.keys(x)` / `.values(x)` call form (#2168 object-entries-map) —
+   * distinct from {@link iterationShape} for the same reason `IRLoop`'s
+   * own field is (see that field's docstring, `packages/jsx/src/types.ts`):
+   * `x` is a plain object, not an array. Threaded from
+   * `IRLoop.objectIteration`.
+   */
+  objectIteration?: 'entries' | 'keys' | 'values'
 }
 
 /**

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

@@ -147,6 +147,38 @@ export function exhaustiveAttrValue(value: never): never {
   throw new Error(`Unhandled AttrValue kind: ${JSON.stringify(value)}`)
 }
 
+/**
+ * Reconstruct the `Object.entries/keys/values(x)` call the compiler
+ * stripped off at IR-build time (`isObjectIteratorCall`, `jsx-to-ir.ts`)
+ * for the CLIENT's array expression — unlike a template adapter, the
+ * client runs real JS, so it just re-wraps the plain object `x` (the
+ * loop's `array`) to get back the actual iterable `mapArray` needs.
+ *
+ * Deliberately does NOT also handle the array-only `iterationShape`
+ * (`arr.entries()`/`.keys()`) — that shape's `mapArray` callback already
+ * gets what it needs from `mapArray`'s own native `(value, index)`
+ * signature (the compiler synthesizes `param`/`index` to match those two
+ * positions directly), so wrapping the array there would double up. See
+ * `IRLoop.objectIteration`'s docstring (`types.ts`) for why the two
+ * fields are distinct, and `applyIterationShape` in `html-template.ts`
+ * (a different consumer — the CSR template-literal's own inline `.map()`
+ * — which does handle both fields, since its shape doesn't reuse
+ * `mapArray`'s positional signature).
+ *
+ * The callback's OWN head (`__bfItem` vs a plain param name) is unrelated
+ * and unaffected — that's `destructureLoopParam`'s job
+ * (`control-flow/shared.ts`), driven entirely by `param`/`paramBindings`.
+ */
+export function applyObjectIterationWrap(
+  node: { objectIteration?: 'entries' | 'keys' | 'values' },
+  arrayExpr: string,
+): string {
+  if (node.objectIteration === 'entries') return `Object.entries(${arrayExpr})`
+  if (node.objectIteration === 'keys') return `Object.keys(${arrayExpr})`
+  if (node.objectIteration === 'values') return `Object.values(${arrayExpr})`
+  return arrayExpr
+}
+
 /**
  * Build the chained array expression for reconcileList. Thin
  * adapter over `buildLoopChainExpr` that unpacks the collected
@@ -156,12 +188,13 @@ export function exhaustiveAttrValue(value: never): never {
  * branch preserves the chain (#1434).
  */
 export function buildChainedArrayExpr(elem: TopLevelLoop | BranchLoop): string {
-  return buildLoopChainExpr({
+  const chained = buildLoopChainExpr({
     base: elem.array,
     sortComparator: elem.sortComparator,
     filterPredicate: elem.filterPredicate,
     chainOrder: elem.chainOrder,
   })
+  return applyObjectIterationWrap(elem, chained)
 }
 
 /**