@barefootjs/jsx 0.18.3 → 0.18.5

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)
 }
 
 /**

package/src/jsx-to-ir.ts

@@ -48,6 +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, decodeEntities } from '@barefootjs/shared'
 
 // =============================================================================
 // Transform Context
@@ -81,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. */
@@ -394,6 +406,7 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
     isRoot: true,
     insideComponentChildren: false,
     loopParams: new Set(),
+    loopDepth: 0,
     patterns: {
       signals: analyzer.signals.map(s => ({
         getter: s.getter,
@@ -1562,7 +1575,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),
   }
 }
@@ -2482,6 +2500,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
@@ -3245,6 +3288,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
@@ -3270,6 +3317,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) => {
@@ -3283,8 +3331,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
@@ -3294,6 +3345,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)
@@ -3444,8 +3507,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),
         )
@@ -3484,7 +3551,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) {
@@ -3503,6 +3570,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
@@ -3625,6 +3693,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),
@@ -3704,6 +3773,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.
@@ -3743,6 +3822,8 @@ function transformMapCall(
     sortComparator,
     chainOrder,
     iterationShape,
+    objectIteration,
+    depth,
     clientOnly: isClientOnly || undefined,
     mapPreamble,
     templateMapPreamble,
@@ -4066,13 +4147,13 @@ function processAttributes(
 
     if (!ts.isJsxAttribute(attr)) continue
 
-    const name = attr.name.getText(ctx.sourceFile)
+    const rawName = attr.name.getText(ctx.sourceFile)
 
     // ref is captured separately (not pushed into `attrs`) because it never
     // appears in the rendered HTML — it's a compile-time binding from the
     // JSX call site to the runtime DOM element, surfaced via the IRElement
     // `ref` field for the client-JS emitter.
-    if (name === 'ref') {
+    if (rawName === 'ref') {
       if (attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
         reportJsxBranchLocalInCallback(attr.initializer.expression, ctx)
         ref = ctx.getJS(attr.initializer.expression)
@@ -4084,13 +4165,13 @@ function processAttributes(
     // they're wired up at hydration time (delegated event registration) and
     // must not leak into rendered HTML. The DOM event name is lowercase
     // (`click`, not `Click`), so strip the `on` prefix and downcase.
-    if (/^on[A-Z]/.test(name)) {
+    if (/^on[A-Z]/.test(rawName)) {
       if (attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
-        const eventName = name.slice(2).toLowerCase()
+        const eventName = rawName.slice(2).toLowerCase()
         reportJsxBranchLocalInCallback(attr.initializer.expression, ctx)
         events.push({
           name: eventName,
-          originalAttr: name,
+          originalAttr: rawName,
           handler: ctx.getJS(attr.initializer.expression),
           loc: getSourceLocation(attr, ctx.sourceFile, ctx.filePath),
         })
@@ -4098,6 +4179,19 @@ function processAttributes(
       continue
     }
 
+    // Normalize the JSX prop spelling to the HTML/SVG attribute name ONCE,
+    // here in Phase 1, so IRAttribute.name is already the name every
+    // adapter emits verbatim (#2172): React-style HTML camelCase aliases
+    // lower (`htmlFor` → `for`, `tabIndex` → `tabindex`, `readOnly` →
+    // the BOOLEAN_ATTRS member `readonly`), SVG presentation attrs
+    // kebab-case (`strokeWidth` → `stroke-width`), case-sensitive SVG XML
+    // names (`viewBox`) and everything unknown (`data-*`, custom-element
+    // attrs) pass through. Previously each adapter re-derived (at most)
+    // `className` → `class` itself and every other alias leaked into the
+    // emitted HTML as an unknown attribute the browser ignores. Intrinsic
+    // elements only — component props (IRProp) keep the user's API names.
+    const name = toHTMLAttrName(rawName)
+
     let value = getAttributeValue(attr, ctx)
     let clientOnly: boolean | undefined
     if (attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
@@ -4143,9 +4237,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} />

package/src/types.ts

@@ -574,6 +574,74 @@ export interface IRLoop {
    */
   iterationShape?: 'entries' | 'keys'
 
+  /**
+   * Pre-`.map()` object iteration (#2168 object-entries-map). Distinct
+   * from {@link iterationShape}, which is scoped ENTIRELY to an array's
+   * own zero-arg `.entries()`/`.keys()`/`.values()` methods — those
+   * synthesize a real numeric index off the array's position, and every
+   * adapter's consumption of `iterationShape` assumes an actual
+   * array/slice underneath.
+   *
+   * `objectIteration` instead records the STATIC `Object.entries(x)` /
+   * `Object.keys(x)` / `Object.values(x)` call form, where `x` is a
+   * plain object/Record (not an array): the "index" bound for `'entries'`
+   * is a STRING KEY, not a numeric position, and the collection an
+   * adapter must iterate is its native map/dict/hash type, not an
+   * array/slice. `transformMapCall` strips the `Object.<method>(...)`
+   * wrapper the same way it strips `arr.entries()` — `array`/`arrayParsed`
+   * end up holding just `x` — and records the shape here so each
+   * adapter's loop renderer picks the right native construct:
+   *
+   *   - `'entries'` → both `index` (bound to the KEY) and `param` (bound
+   *     to the VALUE), synthesized from the 2-element destructure the
+   *     same way `iterationShape: 'entries'` is (see `jsx-to-ir.ts`'s
+   *     `transformMapCall`) — e.g. Jinja `for k, v in x.items()`.
+   *   - `'keys'` → `param` bound to the key only — e.g. Jinja
+   *     `for k in x.keys()`.
+   *   - `'values'` → `param` bound to the value only — e.g. Jinja
+   *     `for v in x.values()`. Unlike the array case, `'values'` is NOT
+   *     a no-op here: `Object.values(x)` genuinely differs from
+   *     iterating `x` itself (`x` isn't iterable at all as a plain
+   *     object), so it must be recorded.
+   *
+   * Iteration ORDER is native-map-dependent: Python `dict`/PHP
+   * array-object/Ruby `Hash` preserve the source object's insertion
+   * order (matching JS `Object.entries()` semantics exactly), so Jinja,
+   * Twig, Blade, and ERB lower directly to their native map/dict/hash
+   * iteration. Go's `map[string]T`, Rust's `BTreeMap` (deliberate design,
+   * see `num.rs`), and Perl's hash (Xslate/Mojolicious) have NO
+   * order-preserving native map type, so those four instead lower to a
+   * DETERMINISTIC SORTED-BY-KEY iteration — Go's `{{range}}` (the
+   * stdlib's own `fmtsort`), minijinja's `BTreeMap` (already sorted),
+   * Kolon's `.kv()`/`.keys()`/`.values()` (verified empirically sorted),
+   * and Mojolicious's explicit `sort keys %$hash` (mirroring the
+   * existing `spread_attrs`/`_style_to_css` convention in
+   * `BarefootJS.pm`). This is a documented, permanent known limitation
+   * relative to JS's insertion-order guarantee (not a follow-up TODO) —
+   * true insertion order is physically unrecoverable from those
+   * languages' native map types once constructed, so sorted order is the
+   * best available deterministic approximation, not an interim refusal.
+   *
+   * Only the OUTERMOST, unchained `Object.<method>(x).map(cb)` shape is
+   * recognized — mirroring `iterationShape`'s own scope, chaining
+   * (`Object.entries(x).filter(pred).map(cb)`) is not (yet) recognized
+   * either, same as the array case.
+   */
+  objectIteration?: 'entries' | 'keys' | 'values'
+
+  /**
+   * Count of enclosing `.map()` loops (0 = outermost, 1 = nested one
+   * level deep, ...). Adapters use this to derive the loop body's
+   * `key`/`data-key` attribute suffix — `depth > 0 ? 'data-key-' +
+   * depth : 'data-key'` — matching `keyAttrName()` in
+   * `ir-to-client-js/utils.ts`, which the CSR path and the Hono SSR
+   * adapter each already derive independently (a recursion counter and
+   * a push/pop stack respectively). Before this field, the 8 template
+   * (non-JS) adapters had no depth awareness at all and always emitted
+   * plain `data-key` on nested-loop items (#2168 nested-loop-outer-binding).
+   */
+  depth: number
+
   /**
    * When true, loop should be evaluated on client side only.
    * SSR adapters should skip rendering and output placeholder markers.