@barefootjs/go-template 0.17.1 → 0.18.0

package/src/adapter/go-template-adapter.ts

@@ -31,6 +31,7 @@ import type {
   IRAsync,
   IRMetadata,
   TemplatePrimitiveRegistry,
+  LoopBindingPathSegment,
 } from '@barefootjs/jsx'
 import {
   BaseAdapter,
@@ -59,7 +60,7 @@ import {
   emitAttrValue,
   augmentInheritedPropAccesses,
   collectContextConsumers,
-  isLowerableObjectRestDestructure,
+  isLowerableLoopDestructure,
   type ContextConsumer,
   collectModuleStringConsts as collectModuleStringConstsShared,
   prepareLoweringMatchers,
@@ -74,6 +75,7 @@ import {
   GO_KEYWORDS,
   capitalize,
   capitalizeFieldName,
+  goFieldNameForKey,
   slotIdToFieldSuffix,
   loopKeyToGoFieldPath,
 } from "./lib/go-naming.ts"
@@ -116,6 +118,7 @@ import {
   jsLiteralToGo,
   objectLiteralToGoMap,
 } from "./value/value-lowering.ts"
+import { parsedLiteralToGo } from "./value/parsed-literal-to-go.ts"
 import { typeInfoToGo } from "./type/type-codegen.ts"
 import { isBooleanMemo, isListFilterMemo, isStringTernaryMemo } from "./memo/memo-type.ts"
 import { lowerCtorExpr } from "./memo/ctor-lowering.ts"
@@ -228,11 +231,36 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
    * wrapper's synthetic scalar field) instead of `.`. Innermost last.
    */
   private loopScalarItemStack: boolean[] = []
+  /**
+   * Per-loop: true when the loop body IS a single component
+   * (`loop.childComponent`), i.e. the range iterates the `.{Name}s` wrapper
+   * slice and `.` inside the body is a wrapper struct that embeds the child's
+   * Props. False for a component merely nested inside an element item
+   * (`<li><Badge/></li>`, #2130), where `.` is the raw datum and the child's
+   * props live on the PARENT's once-per-slot instance (`$.{Name}SlotN`).
+   * Innermost last.
+   */
+  private loopWrapperStack: boolean[] = []
   private loopVarRefCount: Map<string, number> = new Map()
   /** Stack of destructure-param binding maps (binding name → Go accessor on the
-   *  range var, e.g. `id` → `$__bf_item0.Id`, `rest` → `$__bf_item0`). Innermost
-   *  last. Lets `.map(({ id, ...rest }) => …)` resolve instead of BF104. */
+   *  range var, e.g. `id` → `$__bf_item0.Id`, `rest` → `$__bf_item0`, an
+   *  array-rest → `(bf_slice $__bf_item0 1)`, a nested/index path →
+   *  `(index $__bf_item0.Cells 0)`). Innermost last. Lets `.map(({ id, ...rest
+   *  })` / `.map(([k, v]) =>` / nested-path destructure resolve instead of
+   *  BF104 (#2087 Phase B — see `buildDestructureBindingMap`). */
   private loopBindingStack: Array<Map<string, string>> = []
+  /**
+   * Stack of object-rest exclude-key maps, parallel to `loopBindingStack`
+   * (same push/pop points, innermost last). Only object-rest bindings appear
+   * here — keyed by binding name, each entry carries the PARENT accessor
+   * (same value as `loopBindingStack`'s entry for that name) plus the sibling
+   * keys the destructure pattern already pulled out. `emitSpread` consults
+   * this for a `{...rest}` spread onto an intrinsic element, so the residual
+   * omits exactly the keys the pattern destructured — member reads
+   * (`rest.flag`) don't need it and keep resolving through `loopBindingStack`
+   * alone (#2087 Phase B).
+   */
+  private loopRestExcludeStack: Array<Map<string, { parent: string; excludeKeys: string[] }>> = []
 
   /**
    * Cross-component child shapes, keyed by child component name. Populated via
@@ -475,9 +503,12 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
 
   /**
    * Register a child component's shape (see `childComponentShapes`). Call once
-   * per known child IR before the parent's `generateTypes`. Idempotent.
+   * per known child IR before the parent's `generateTypes`. Idempotent. Takes
+   * only the IR's `metadata` so orchestrators that never build the full IR
+   * (the CLI's cross-file shape pre-pass, #2131) can register from a bare
+   * analyzer pass — a full `ComponentIR` still satisfies it structurally.
    */
-  registerChildComponentShape(ir: ComponentIR): void {
+  registerChildComponentShape(ir: Pick<ComponentIR, 'metadata'>): void {
     const name = ir.metadata.componentName
     if (!name) return
     const paramNames = new Set((ir.metadata.propsParams ?? []).map(p => p.name))
@@ -507,10 +538,37 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     return capitalizeFieldName(c.localName)
   }
 
+  /**
+   * True when `node` is (or is a member access rooted in) a `useContext`
+   * local with an object-shaped `createContext` default — see `member()`'s
+   * `bf_get` branch. Recurses through non-computed member chains: once a
+   * chain is rooted in a map, every further `.property` down the chain reads
+   * off an `interface{}` value with no static struct to fall back to, so it
+   * stays map-rooted for `bf_get` too.
+   */
+  private isMapRootedContextChain(node: ParsedExpr): boolean {
+    if (node.kind === 'identifier') {
+      return this.state.contextConsumers.some(
+        c => c.localName === node.name && c.defaultKind === 'object',
+      )
+    }
+    if (node.kind === 'member' && !node.computed) {
+      return this.isMapRootedContextChain(node.object)
+    }
+    return false
+  }
+
   /** Go type for a context-consumer field, from its `createContext` default's type. */
   private contextConsumerGoType(c: ContextConsumer): string {
     if (typeof c.defaultValue === 'number') return 'int'
     if (typeof c.defaultValue === 'boolean') return 'bool'
+    // An OBJECT-shaped default (`createContext<{ config: X }>({ config: {} })`,
+    // #2087) needs a real map type, not the scalar `string` fallback below: a
+    // descendant's `ctx.config.label` read lowers through `bf_get` (see
+    // `member()`), which needs an actual `map[string]interface{}` receiver to
+    // walk — a `string` field crashes real `go run` execution with `can't
+    // evaluate field Config in type string`.
+    if (c.defaultKind === 'object') return 'map[string]interface{}'
     return 'string'
   }
 
@@ -519,6 +577,14 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     if (typeof c.defaultValue === 'number') return String(c.defaultValue)
     if (typeof c.defaultValue === 'boolean') return String(c.defaultValue)
     if (typeof c.defaultValue === 'string') return `"${escapeGoString(c.defaultValue)}"`
+    // Object-shaped default: a real (nil-safe) empty map — see
+    // `contextConsumerGoType`. The `createContext` argument's actual nested
+    // shape (`{ config: {} }`) is never baked key-for-key here: a consumer
+    // only ever reads this DEFAULT when no enclosing Provider ran, and
+    // `bf_get` (getFieldValue) already returns nil safely for any missing/
+    // absent key off an empty map, so `ctx.config.label ?? 'none'` resolves
+    // to `'none'` regardless of how deep the default's own nesting goes.
+    if (c.defaultKind === 'object') return 'map[string]interface{}{}'
     return '""'
   }
 
@@ -591,16 +657,23 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
    * analyzer's structured properties (no definition-string parsing). Both the
    * struct emitter and the object-literal baker consume it, so a baked literal
    * can't name a field the struct lacks. A non-Go-identifier source key
-   * (`"data-id"`, a numeric key) is dropped here, so the baker bails to nil for
-   * any literal using such a key.
+   * (`"data-priority"`, a numeric key) still gets a field via
+   * `goFieldNameForKey`'s segment-splitting PascalCase (#2087 Phase B —
+   * `rest-destructure-object-spread-in-map`'s `'data-priority'` residual key
+   * needs a real field to bake into, or the whole literal defers to nil); a
+   * dedup guard drops a later key that sanitizes to a Go name already taken
+   * (rare, but two fields can't share one Go identifier).
    */
   private structFieldsFor(td: TypeDefinition): Array<{ tsName: string; goName: string; goType: string }> {
     const fields: Array<{ tsName: string; goName: string; goType: string }> = []
+    const seenGoNames = new Set<string>()
     for (const prop of td.properties ?? []) {
-      if (!GO_IDENTIFIER.test(prop.name)) continue
+      const goName = goFieldNameForKey(prop.name)
+      if (seenGoNames.has(goName)) continue
+      seenGoNames.add(goName)
       fields.push({
         tsName: prop.name,
-        goName: capitalizeFieldName(prop.name),
+        goName,
         goType: typeInfoToGo(this.emitCtx, prop.type),
       })
     }
@@ -928,10 +1001,13 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
   }
 
   /** Collect static child instances from loop body children for the wrapper struct. */
-  private collectBodyChildInstances(bodyChildren: IRNode[]): StaticChildInstance[] {
+  private collectBodyChildInstances(
+    bodyChildren: IRNode[],
+    propsParams: ReadonlyArray<{ name: string }> = [],
+  ): StaticChildInstance[] {
     const result: StaticChildInstance[] = []
     for (const child of bodyChildren) {
-      this.collectStaticChildInstancesRecursive(child, result, false, new Map())
+      this.collectStaticChildInstancesRecursive(child, result, false, new Map(), propsParams)
     }
     return result
   }
@@ -1184,8 +1260,17 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     for (const c of this.nonCollidingContextConsumers(takenInit)) {
       const field = this.contextFieldName(c)
       const def = this.contextConsumerGoDefault(c)
+      // A `map[string]interface{}` field's Go zero value (nil) is already a
+      // safely-readable "no value" (`bf_get` / `getFieldValue` treats a nil
+      // map exactly like an empty one, per `reflect.Value.MapIndex`'s
+      // documented nil-map behavior) — no `applyGoFallback` wrapper needed,
+      // same as the other zero-value sentinels below.
       const defaulted =
-        c.defaultValue === null || def === '""' || def === '0' || def === 'false'
+        c.defaultValue === null ||
+        def === '""' ||
+        def === '0' ||
+        def === 'false' ||
+        def === 'map[string]interface{}{}'
           ? `in.${field}`
           : applyGoFallback(`in.${field}`, def)
       lines.push(`\t\t${field}: ${defaulted},`)
@@ -1200,7 +1285,7 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
   }
 
   private emitStaticChildInstances(lines: string[], ir: ComponentIR): void {
-    const staticChildren = this.collectStaticChildInstances(ir.root)
+    const staticChildren = this.collectStaticChildInstances(ir.root, ir.metadata.propsParams)
     for (const child of staticChildren) {
       lines.push(`\t\t${child.fieldName}: New${child.name}Props(${child.name}Input{`)
       lines.push(`\t\t\tScopeID: scopeID + "_${child.slotId}",`)
@@ -1407,7 +1492,7 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       const varName = `${nested.name.charAt(0).toLowerCase()}${nested.name.slice(1)}s`
       const wrapperType = this.loopBodyWrapperName(componentName, nested)
       const datumFields = this.resolveLoopDatumFields(nested.loopItemType)
-      const bodyChildInstances = this.collectBodyChildInstances(nested.bodyChildren!)
+      const bodyChildInstances = this.collectBodyChildInstances(nested.bodyChildren!, ir.metadata.propsParams)
 
       for (const child of bodyChildInstances) {
         const childVar = `child_${child.fieldName}`
@@ -1501,7 +1586,7 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       const wrapperType = this.loopBodyWrapperName(componentName, nested)
       const varName = `${nested.name.charAt(0).toLowerCase()}${nested.name.slice(1)}s`
       const datumFields = this.resolveLoopDatumFields(nested.loopItemType)
-      const bodyChildInstances = this.collectBodyChildInstances(nested.bodyChildren!)
+      const bodyChildInstances = this.collectBodyChildInstances(nested.bodyChildren!, ir.metadata.propsParams)
 
       // Child sub-component instances created once (identical scope IDs per row).
       for (const child of bodyChildInstances) {
@@ -1826,7 +1911,7 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       }
     }
 
-    const staticChildren = this.collectStaticChildInstances(ir.root)
+    const staticChildren = this.collectStaticChildInstances(ir.root, ir.metadata.propsParams)
     for (const child of staticChildren) {
       lines.push(`\t${child.fieldName} ${child.name}Props \`json:"-"\``)
     }
@@ -1850,9 +1935,12 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
    * components inside loops (handled by nestedComponents). Each instance carries
    * its component `name`, `slotId`, `props`, and Go `fieldName`.
    */
-  private collectStaticChildInstances(node: IRNode): Array<StaticChildInstance> {
+  private collectStaticChildInstances(
+    node: IRNode,
+    propsParams: ReadonlyArray<{ name: string }> = [],
+  ): Array<StaticChildInstance> {
     const result: StaticChildInstance[] = []
-    this.collectStaticChildInstancesRecursive(node, result, false, new Map())
+    this.collectStaticChildInstancesRecursive(node, result, false, new Map(), propsParams)
     return result
   }
 
@@ -1925,6 +2013,7 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     result: StaticChildInstance[],
     inLoop: boolean,
     providerCtx: ReadonlyMap<string, string>,
+    propsParams: ReadonlyArray<{ name: string }> = [],
   ): void {
     if (node.type === 'component') {
       const comp = node as IRComponent
@@ -1934,7 +2023,7 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       // child components nested inside still get their slot fields.
       if (comp.dynamicTag) {
         for (const child of comp.children) {
-          this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx)
+          this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx, propsParams)
         }
         return
       }
@@ -1966,86 +2055,208 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
         // never contain components (any nested component renders a `{{template}}`
         // action, which the bake extractors reject), so recursing is a no-op.
         for (const child of effectiveChildren) {
-          this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx)
+          this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx, propsParams)
         }
       }
       // Recurse into Portal's children to find nested components
       if (comp.name === 'Portal' && comp.children) {
         for (const child of comp.children) {
-          this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx)
+          this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx, propsParams)
         }
       }
     } else if (node.type === 'loop') {
       const loop = node as IRLoop
-      // Mark children as inside loop
+      // A loop whose body IS a single component is the nestedComponents /
+      // wrapper-slice machinery's case — mark its subtree as in-loop so the
+      // component (and its body children, which live on the wrapper struct)
+      // are skipped here. A component merely nested inside an element item
+      // (`<li><Badge/></li>`, #2130) gets NO wrapper slice: keep collecting,
+      // so it registers a normal once-per-slot instance (shared across rows,
+      // like the wrapper's `bodyChildInstances`); per-item content reaches it
+      // through the loop-body children define (see `renderComponent`).
       for (const child of loop.children) {
-        this.collectStaticChildInstancesRecursive(child, result, true, providerCtx)
+        this.collectStaticChildInstancesRecursive(
+          child,
+          result,
+          inLoop || !!loop.childComponent,
+          providerCtx,
+          propsParams,
+        )
       }
     } else if (node.type === 'element') {
       const element = node as IRElement
       for (const child of element.children) {
-        this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx)
+        this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx, propsParams)
       }
     } else if (node.type === 'fragment') {
       const fragment = node as IRFragment
       for (const child of fragment.children) {
-        this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx)
+        this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx, propsParams)
       }
     } else if (node.type === 'conditional') {
       const cond = node as IRConditional
-      this.collectStaticChildInstancesRecursive(cond.whenTrue, result, inLoop, providerCtx)
+      this.collectStaticChildInstancesRecursive(cond.whenTrue, result, inLoop, providerCtx, propsParams)
       if (cond.whenFalse) {
-        this.collectStaticChildInstancesRecursive(cond.whenFalse, result, inLoop, providerCtx)
+        this.collectStaticChildInstancesRecursive(cond.whenFalse, result, inLoop, providerCtx, propsParams)
       }
     } else if (node.type === 'if-statement') {
       // An early-return if-statement root (e.g. an asChild split) keeps its
       // subtrees in consequent/alternate — the non-asChild branch's nested icon
       // needs its slot field like any other static child.
       const stmt = node as IRIfStatement
-      this.collectStaticChildInstancesRecursive(stmt.consequent, result, inLoop, providerCtx)
+      this.collectStaticChildInstancesRecursive(stmt.consequent, result, inLoop, providerCtx, propsParams)
       if (stmt.alternate) {
-        this.collectStaticChildInstancesRecursive(stmt.alternate, result, inLoop, providerCtx)
+        this.collectStaticChildInstancesRecursive(stmt.alternate, result, inLoop, providerCtx, propsParams)
       }
     } else if (node.type === 'provider') {
       // SSR context propagation: record the provider's value against its context
       // name and extend the active binding map for descendants. A literal value
-      // lowers to a Go literal; a non-literal is left unbound (the consumer
-      // keeps its default).
+      // lowers to a Go literal; an object-literal value lowers to a Go map when
+      // every member is a supported shape (#2087 — see `extendProviderContext`);
+      // anything else is left unbound (the consumer keeps its default).
       const p = node as IRProvider
-      const childCtx = this.extendProviderContext(providerCtx, p)
+      const childCtx = this.extendProviderContext(providerCtx, p, propsParams)
       for (const child of p.children) {
-        this.collectStaticChildInstancesRecursive(child, result, inLoop, childCtx)
+        this.collectStaticChildInstancesRecursive(child, result, inLoop, childCtx, propsParams)
       }
     } else if (node.type === 'async') {
       // Async fallback + children render server-side via the OOS
       // protocol; static child components inside them still need slot
       // fields on the parent struct.
       const a = node as IRAsync
-      this.collectStaticChildInstancesRecursive(a.fallback, result, inLoop, providerCtx)
+      this.collectStaticChildInstancesRecursive(a.fallback, result, inLoop, providerCtx, propsParams)
       for (const child of a.children) {
-        this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx)
+        this.collectStaticChildInstancesRecursive(child, result, inLoop, providerCtx, propsParams)
       }
     }
   }
 
   /**
    * Extend the active provider-context map with one `<Ctx.Provider value>`. A
-   * string/number/boolean literal value is lowered to a Go literal; any other
-   * shape is skipped (the descendant consumer keeps its `createContext` default).
+   * string/number/boolean literal value is lowered to a Go literal. An
+   * OBJECT-LITERAL value (#2087's chart shape — `value={{ config: props.config
+   * ?? {} }}`) lowers to a `map[string]interface{}` Go expression via
+   * `providerObjectValueToGoMap` when every member is a supported shape; any
+   * other shape (including a partially-supported object literal) is skipped —
+   * the descendant consumer keeps its `createContext` default, unchanged from
+   * before this method understood objects at all.
    */
   private extendProviderContext(
     current: ReadonlyMap<string, string>,
     p: IRProvider,
+    propsParams: ReadonlyArray<{ name: string }>,
   ): ReadonlyMap<string, string> {
-    const v = p.valueProp?.value as { kind?: string; value?: unknown } | undefined
-    if (!v || v.kind !== 'literal') return current
-    let goLit: string | null = null
-    if (typeof v.value === 'string') goLit = `"${escapeGoString(v.value)}"`
-    else if (typeof v.value === 'number' || typeof v.value === 'boolean') goLit = String(v.value)
-    if (goLit === null) return current
-    const next = new Map(current)
-    next.set(p.contextName, goLit)
-    return next
+    const v = p.valueProp?.value as
+      | { kind?: string; value?: unknown; parsed?: ParsedExpr }
+      | undefined
+    if (!v) return current
+    if (v.kind === 'literal') {
+      let goLit: string | null = null
+      if (typeof v.value === 'string') goLit = `"${escapeGoString(v.value)}"`
+      else if (typeof v.value === 'number' || typeof v.value === 'boolean') goLit = String(v.value)
+      if (goLit === null) return current
+      const next = new Map(current)
+      next.set(p.contextName, goLit)
+      return next
+    }
+    if (v.kind === 'expression' && v.parsed) {
+      const goMap = this.providerObjectValueToGoMap(v.parsed, propsParams)
+      if (goMap !== null) {
+        const next = new Map(current)
+        next.set(p.contextName, goMap)
+        return next
+      }
+    }
+    return current
+  }
+
+  /**
+   * Lower a `<Ctx.Provider value={{ … }}>` object literal to a Go
+   * `map[string]interface{}{…}` expression, for binding into a static child's
+   * context-consumer field (`emitStaticChildInstances`). Keys keep their
+   * SOURCE (JS-cased) names — the consumer reads them back via `bf_get`
+   * (`member()`), which is case-tolerant (`getFieldValue`, bf.go), so casing
+   * doesn't have to match a capitalized Go field.
+   *
+   * Every member must lower through `lowerProviderMapMemberValue` for the
+   * WHOLE object to lower — a single unsupported member (a getter, a
+   * function, an expression outside the narrow surface below) fails the
+   * whole value and returns `null`, exactly like the pre-#2087 refusal (the
+   * consumer then keeps its `createContext` default).
+   */
+  private providerObjectValueToGoMap(
+    parsed: ParsedExpr,
+    propsParams: ReadonlyArray<{ name: string }>,
+  ): string | null {
+    if (parsed.kind !== 'object-literal') return null
+    const entries: string[] = []
+    for (const prop of parsed.properties) {
+      if (prop.shorthand) return null
+      const goVal = this.lowerProviderMapMemberValue(prop.value, propsParams)
+      if (goVal === null) return null
+      entries.push(`${JSON.stringify(prop.key)}: ${goVal}`)
+    }
+    if (entries.length === 0) return null
+    return `map[string]interface{}{${entries.join(', ')}}`
+  }
+
+  /**
+   * Lower one member VALUE of a provider object literal to a Go expression.
+   * Supports:
+   *   - a pure literal / nested literal array-or-object (same machinery
+   *     `objectLiteralToGoMap` uses for an inline object passed to a child's
+   *     optional object prop);
+   *   - `props.<X> ?? {}` (#2087's exact chart shape) — an optional prop with
+   *     an empty-object fallback. The referenced prop's OWN Go field is
+   *     `interface{}` (a `Record<string, X>` type-alias prop never becomes a
+   *     named Go struct — see `typeInfoToGo`'s `interface` case — so it can't
+   *     be typed `map[string]interface{}` without risking an unrelated
+   *     `ui/compat.lock.json` diff across every other `interface{}`-typed
+   *     prop). Recovering the caller-supplied map goes through the runtime's
+   *     `bf.AsMap` normalizer rather than a bare
+   *     `.(map[string]interface{})` type assertion: an `interface{}` field
+   *     can legally hold ANY string-keyed map kind — a Go handler modelling
+   *     `Record<string, string>` naturally passes `map[string]string` — and
+   *     the single-type assertion would silently drop those values (#2111
+   *     review). `bf.AsMap` returns nil for nil / typed-nil / non-map
+   *     values, so the emitted fallback still lands on a real, empty map,
+   *     matching JS `??`'s "assign the real value when present, else `{}`"
+   *     semantics.
+   * Anything else (a getter/callback member, an unresolvable expression)
+   * returns `null`, failing the WHOLE containing object (see
+   * `providerObjectValueToGoMap`).
+   */
+  private lowerProviderMapMemberValue(
+    node: ParsedExpr,
+    propsParams: ReadonlyArray<{ name: string }>,
+  ): string | null {
+    if (node.kind === 'object-literal') return objectLiteralToGoMap(this.emitCtx, node)
+    const literal = parsedLiteralToGo(this.emitCtx, node)
+    if (literal !== null) return literal
+    if (
+      node.kind === 'logical' &&
+      node.op === '??' &&
+      node.right.kind === 'object-literal' &&
+      node.right.properties.length === 0 &&
+      node.left.kind === 'member' &&
+      !node.left.computed &&
+      node.left.object.kind === 'identifier' &&
+      node.left.object.name === this.state.propsObjectName
+    ) {
+      // Bound to a local so the narrowed `member` shape survives into the
+      // closure below — TS drops property-path narrowing (`node.left.kind
+      // === 'member'`) across a nested arrow function boundary.
+      const propName = node.left.property
+      if (propsParams.some(param => param.name === propName)) {
+        const fieldRef = `in.${capitalizeFieldName(propName)}`
+        return (
+          `func() map[string]interface{} { ` +
+          `if m := bf.AsMap(${fieldRef}); m != nil { return m }; ` +
+          `return map[string]interface{}{} }()`
+        )
+      }
+    }
+    return null
   }
 
   /**
@@ -2846,10 +3057,10 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     if (objHO && (objHO.method === 'find' || objHO.method === 'findLast')) {
       const findResult = this.renderHigherOrderExpr(objHO, emit)
       if (findResult) {
-        return `{{with ${findResult}}}{{.${capitalizeFieldName(property)}}}{{end}}`
+        return `{{with ${findResult}}}{{.${goFieldNameForKey(property)}}}{{end}}`
       }
       const templateBlock = this.renderFindTemplateBlock(
-        objHO, emit, capitalizeFieldName(property),
+        objHO, emit, goFieldNameForKey(property),
       )
       if (templateBlock) return templateBlock
     }
@@ -2860,6 +3071,22 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       return this.rootFieldRef(property)
     }
 
+    // A member chain rooted in a `useContext` local whose `createContext`
+    // default is object-shaped (#2087 — `defaultKind === 'object'`) reads off
+    // a `map[string]interface{}` field, not a struct: plain Go template dot
+    // access (`.Ctx.Config`) does an EXACT-string `MapIndex`, so it would
+    // only resolve a capitalized key the provider never bakes (see
+    // `providerObjectValueToGoMap`, which keeps SOURCE/JS-cased keys). Route
+    // through `bf_get` (the runtime's case-tolerant `getFieldValue`, bf.go)
+    // instead, recursively — once a chain is map-rooted every further
+    // `.property` is ALSO opaque (the map's value type is `interface{}`, so
+    // there's no static struct to fall back to), hence checking the object
+    // rather than just the top-level identifier.
+    if (this.isMapRootedContextChain(object)) {
+      const objGo = emit(object)
+      return `bf_get ${wrapIfMultiToken(objGo)} ${JSON.stringify(property)}`
+    }
+
     // Static property access on a module object-literal const
     // (`variantClasses.ghost` in a class template literal) resolves at compile
     // time — same lookup as the bracket-index form in
@@ -2874,14 +3101,22 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
 
     // Inside a loop, the loop param variable refers to the current item
     // (dot). e.g. `msg.role` inside `{{range $_, $msg := .Messages}}` → `.Role`
+    //
+    // Field names route through `goFieldNameForKey` — the same sanitizer the
+    // struct/map bake side uses — NOT bare `capitalizeFieldName`: a
+    // non-identifier property (`meta["data-x"]`, parsed as computed member
+    // access) would otherwise emit `.Data-x`, which is not even valid Go
+    // template syntax, let alone a reachable field (PR #2089 review). For
+    // identifier keys (snake_case included) the two functions agree, so
+    // nothing previously reachable changes shape.
     const currentLoopParam = this.loopParamStack[this.loopParamStack.length - 1]
     if (object.kind === 'identifier' && currentLoopParam && object.name === currentLoopParam) {
-      return `.${capitalizeFieldName(property)}`
+      return `.${goFieldNameForKey(property)}`
     }
 
     const obj = emit(object)
     if (property === 'length') return `len ${obj}`
-    return `${obj}.${capitalizeFieldName(property)}`
+    return `${obj}.${goFieldNameForKey(property)}`
   }
 
   indexAccess(object: ParsedExpr, index: ParsedExpr, emit: (e: ParsedExpr) => string): string {
@@ -3028,11 +3263,36 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
   }
 
   objectLiteral(_properties: ObjectLiteralProperty[], raw: string, _emit: (e: ParsedExpr) => string): string {
-    // Not yet lowered structurally from `properties`: route through the
-    // `unsupported` path (`[UNSUPPORTED: …]`). Object values that DO reach a Go
-    // map today (signal/const inits, spread bags) go through the dedicated
+    // The shared `isSupported` gate now admits an EMPTY object literal
+    // (`?? {}`) as `??`'s right operand (expression-parser.ts, `logical`
+    // case) — every other adapter has a native `{}` dict/hashref literal to
+    // emit here, but `text/template` has none, so this dispatcher is the
+    // one place left to refuse the shape. Unlike the sibling adapters, Go
+    // can't silently fall back to a safe sentinel text: `this.unsupported`'s
+    // `[UNSUPPORTED: …]` marker would be spliced into a Go template action
+    // (e.g. as an `or`/`and` operand) and break template parsing, and the
+    // shared gate no longer reports BF101 for this shape itself (it now
+    // considers `x ?? {}` supported). So self-report BF101 here — mirroring
+    // the other self-contained refusals in this file (`pushCallbackBF101`,
+    // `refuseFilterExprNode`) — and return the safe `""` string sentinel,
+    // which is always a valid Go template value in every position `??`'s
+    // result can land in. Object values that DO reach a Go map today
+    // (signal/const inits, spread bags) go through the dedicated
     // `objectLiteralToGoMap` lowering, not here.
-    return this.unsupported(raw, 'object literal')
+    // `raw` is the whole top-level expression's source text (threaded
+    // unchanged through `convertNode`, same convention every `unsupported`
+    // node relies on for its diagnostic) — e.g. `props.config ?? {}`, not
+    // just the `{}` sub-node — so it reads naturally in the message below.
+    this.state.errors.push({
+      code: 'BF101',
+      severity: 'error',
+      message: `Expression not supported: ${raw}`,
+      loc: this.makeLoc(),
+      suggestion: {
+        message: `Go templates have no object/map literal syntax, so the \`?? {}\` fallback can't render server-side. ${GO_REMEDIATION_OPTIONS}`,
+      },
+    })
+    return `""`
   }
 
   /** Set of predicate (boolean-callback) higher-order methods. */
@@ -3328,7 +3588,23 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     }
   }
 
-  flatMethod(object: ParsedExpr, depth: FlatDepth, emit: (e: ParsedExpr) => string): string {
+  flatMethod(
+    object: ParsedExpr,
+    depth: FlatDepth | { expr: ParsedExpr },
+    emit: (e: ParsedExpr) => string,
+  ): string {
+    if (typeof depth === 'object') {
+      // Dynamic depth (#2094) → `bf_flat_dynamic <recv> <renderedDepthExpr>`,
+      // a SEPARATE runtime helper from `bf_flat` below. `bf_flat`'s `-1`
+      // argument is a compile-time SENTINEL meaning "flatten fully"
+      // (`Infinity` normalised at parse time); a genuinely dynamic render-time
+      // value of `-1` means the JS-correct OPPOSITE (no flatten — negative
+      // depth never recurses). Reusing `bf_flat` for both would silently
+      // invert that case, so the dynamic form routes through `FlatDynamicDepth`
+      // (`bf.go`), which performs full `ToIntegerOrInfinity` coercion from
+      // scratch on whatever value the rendered expression evaluates to.
+      return `bf_flat_dynamic ${wrapIfMultiToken(emit(object))} ${wrapIfMultiToken(emit(depth.expr))}`
+    }
     // `.flat(depth?)` → `bf_flat <recv> <depth>`. `Infinity` lowers to the `-1`
     // sentinel (flatten fully); a finite depth flattens that many levels
     // (`0` = shallow copy).
@@ -4414,20 +4690,78 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
   }
 
   /**
-   * Map each destructure binding to its Go accessor on the range var: a named
-   * binding → `$<rangeVar>.<Field>`, an object-rest binding → the bare
-   * `$<rangeVar>` so the member emitter renders `rest.flag` → `$<rangeVar>.Flag`.
+   * Walk a destructure binding's structured `segments` path (#2087 Phase A) into
+   * a Go accessor over `base`. A `field` step appends `.<GoFieldName>` — dot
+   * access resolves against a struct field OR a map key (Go template's
+   * `evalField` supports both), and `goFieldNameForKey` produces a valid Go
+   * identifier regardless of whether the SOURCE key was one (`cells` → `Cells`,
+   * `data-priority` → `DataPriority`) — Go dot-syntax only requires the EMITTED
+   * name to be a legal identifier, not the original JS key. An `index` step
+   * has no dot-notation form, so it wraps in Go's `index` builtin
+   * (`(index <acc> N)`); the wrap also parenthesises the whole accessor so a
+   * following step or an outer composition (`len (...)`) can't swallow it as
+   * extra call arguments.
+   */
+  private buildSegmentAccessor(base: string, segments: readonly LoopBindingPathSegment[]): string {
+    let acc = base
+    for (const seg of segments) {
+      acc = seg.kind === 'field' ? `${acc}.${goFieldNameForKey(seg.key)}` : `(index ${acc} ${seg.index})`
+    }
+    return acc
+  }
+
+  /**
+   * Map each destructure binding to its Go accessor on the range var (#2087
+   * Phase B — `isLowerableLoopDestructure` admits every shape below):
+   *
+   *   - fixed binding (any depth): the FULL `segments` path over the range var
+   *     (`id` → `$item.Id`, `head` in `cells: [head]` → `(index $item.Cells 0)`,
+   *     `k` in `[k, v]` → `(index $item 0)`).
+   *   - array-rest (`[first, ...tail]`): the PARENT `segments` prefix wrapped in
+   *     `bf_slice` (`tail` → `(bf_slice $item 1)`) — this IS the binding's whole
+   *     value, so it composes correctly both bare and under `.length` (`len
+   *     (bf_slice $item 1)`, via the `member()` emitter's generic `len <obj>`
+   *     arm).
+   *   - object-rest (`{ id, ...rest }`): the bare PARENT accessor, so a member
+   *     read (`rest.flag`) renders `$item.Flag` — the simplest lowering that
+   *     keeps the already-green `rest-destructure-object-in-map` fixture byte-
+   *     exact. A `{...rest}` SPREAD needs the residual (item minus the
+   *     destructured siblings), which this map alone can't express; that case
+   *     is tracked separately in the returned `restExcludes` map and consumed
+   *     by `emitSpread`'s `bf_omit` lowering, not through this binding value.
    */
-  private buildDestructureBindingMap(loop: IRLoop, rangeVar: string): Map<string, string> {
-    const m = new Map<string, string>()
+  private buildDestructureBindingMap(
+    loop: IRLoop,
+    rangeVar: string,
+  ): {
+    bindings: Map<string, string>
+    restExcludes: Map<string, { parent: string; excludeKeys: string[] }>
+  } {
+    const bindings = new Map<string, string>()
+    const restExcludes = new Map<string, { parent: string; excludeKeys: string[] }>()
+    const base = `$${rangeVar}`
     for (const b of loop.paramBindings ?? []) {
-      if (b.rest) {
-        m.set(b.name, `$${rangeVar}`)
+      const parent = this.buildSegmentAccessor(base, b.segments ?? [])
+      if (!b.rest) {
+        bindings.set(b.name, parent)
+      } else if (b.rest.kind === 'array') {
+        bindings.set(b.name, `(bf_slice ${parent} ${b.rest.from})`)
       } else {
-        m.set(b.name, `$${rangeVar}.${capitalizeFieldName(b.path.slice(1))}`)
+        bindings.set(b.name, parent)
+        restExcludes.set(b.name, { parent, excludeKeys: b.rest.exclude.map(k => k.key) })
       }
     }
-    return m
+    return { bindings, restExcludes }
+  }
+
+  /** Innermost-first lookup mirroring `loopBindingStack`'s search in
+   * `identifier()`, but over the object-rest exclude-key side table. */
+  private lookupRestExclude(name: string): { parent: string; excludeKeys: string[] } | undefined {
+    for (let i = this.loopRestExcludeStack.length - 1; i >= 0; i--) {
+      const info = this.loopRestExcludeStack[i].get(name)
+      if (info) return info
+    }
+    return undefined
   }
 
   renderLoop(loop: IRLoop): string {
@@ -4446,15 +4780,17 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     //
     // Check the IR's structured `paramBindings` field rather than string-matching
     // `loop.param`: Phase 1 populates it iff the param is a destructure pattern,
-    // and the structured check is robust to formatting variants. A destructure
-    // param is lowerable only for the object-rest / simple-field shape
-    // (`.map(({ id, title, ...rest }) => …)`, `rest` read via member access):
-    // each binding resolves to a field on a named range var (`$__bf_item0.Id`,
-    // `rest.flag` → `$__bf_item0.Flag`). Array-index / nested / rest-spread
-    // shapes (`[a, ...t]`, `{ cells: [h] }`, `{...rest}`) still need machinery
-    // Go's `{{range}}` can't express inline → BF104.
+    // and the structured check is robust to formatting variants. `isLowerableLoopDestructure`
+    // (#2087 Phase A/B) admits fixed bindings at ANY depth (`.field`, array-index,
+    // nested combinations of either — `buildSegmentAccessor` walks the structured
+    // `segments` path), array-rest (`[a, ...t]` → `bf_slice`), and object-rest
+    // whose every use is a member read (`rest.flag`) or a `{...rest}` spread onto
+    // an intrinsic element (→ `bf_omit`, see `emitSpread`). Still refused (BF104):
+    // a bare-value object-rest use (`String(rest)`, `{rest}`, spread onto a
+    // component), and a `.filter().map(destructure)` chain — those need either the
+    // actual residual object or a filter-param retarget this lowering doesn't do.
     const destructure = !!(loop.paramBindings && loop.paramBindings.length > 0)
-    const supportableDestructure = destructure && isLowerableObjectRestDestructure(loop)
+    const supportableDestructure = destructure && isLowerableLoopDestructure(loop)
     if (destructure && !supportableDestructure) {
       this.state.errors.push({
         code: 'BF104',
@@ -4471,6 +4807,42 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       })
     }
 
+    // A loop array that's a bare reference to a FUNCTION-SCOPE local const with
+    // a computed initializer (`const entries = Object.entries(props.x ??
+    // {}).filter(...)`) can't be bound as a Go template value: module-scope
+    // consts (`isModule`) are a different, already-working case (statically
+    // evaluated and seeded into the render context elsewhere), but a
+    // function-scope local only reaches the template at all via
+    // `computeDerivedConstFields`'s STRING-typed derived-const lowering
+    // (`isStringExpr`) — an array-typed initializer like this one never
+    // qualifies, so `identifier()` would still emit `.Entries` (the naive
+    // `rootFieldRef` fallback) while `generateTypes` emits no such field.
+    // `html/template` resolves struct fields dynamically at EXECUTE time, not
+    // at Go compile time, so left unchecked this fails loudly only when the
+    // template actually runs (`can't evaluate field Entries in type
+    // ...Props`) instead of at build time. Pre-existing, general limitation,
+    // orthogonal to #2087's destructure-binding work — newly reachable in this
+    // adapter's test corpus only because the widened destructure gate (#2087
+    // Phase A/B) no longer refuses `static-array-from-props`'s `([emoji,
+    // users]) => ...` param first. Cross-adapter policy: Jinja / ERB apply the
+    // same narrow check in their own `renderLoop` (see `jinja-adapter.ts`).
+    const arrayName = loop.array.trim()
+    if (/^[A-Za-z_$][\w$]*$/.test(arrayName)) {
+      const arrayConst = this.state.localConstants.find(c => c.name === arrayName)
+      if (arrayConst && !arrayConst.isModule && arrayConst.parsed && !this.isStringExpr(arrayConst.parsed, new Set())) {
+        this.state.errors.push({
+          code: 'BF101',
+          severity: 'error',
+          message: `Loop array \`${arrayName}\` is a local computed value (\`${arrayConst.value}\`) that the Go template adapter cannot bind as a template variable — only a string-derived local resolves to a generated struct field.`,
+          loc: loop.loc ?? this.makeLoc(),
+          suggestion: {
+            message:
+              'Pre-compute the array server-side and pass it as a prop, or mark the loop position as @client-only so it runs in JS on the client.',
+          },
+        })
+      }
+    }
+
     let goArray = this.convertExpressionToGo(loop.array)
     const param = loop.param
     let index = loop.index || '_'
@@ -4491,11 +4863,18 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       rangeValue = '_'
     }
 
-    // If the loop contains a component child, range over `.{ComponentName}s`,
-    // which carries a ScopeID per item (TodoItem → `.TodoItems`).
-    const childComponent = this.findChildComponent(loop.children)
-    if (childComponent) {
-      goArray = `.${childComponent.name}s`
+    // If the loop body IS a single component, range over `.{ComponentName}s`,
+    // which carries a ScopeID per item (TodoItem → `.TodoItems`). Gate on the
+    // IR's `loop.childComponent` — the SAME condition `findNestedComponents`
+    // uses to generate that slice field — not on a deep search of the body:
+    // a component merely nested inside an element item (`<li><Badge/></li>`)
+    // generates NO `.Badges` slice, so retargeting the range at it 500s at
+    // render with `can't evaluate field Badges in type *XxxProps` (#2130).
+    // Such loops keep iterating the real collection; the nested child renders
+    // through the parent's once-per-slot instance (see `renderComponent`'s
+    // non-wrapper in-loop branch).
+    if (loop.childComponent) {
+      goArray = `.${loop.childComponent.name}s`
     }
 
     this.inLoop = true
@@ -4513,7 +4892,9 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     if (supportableDestructure) {
       // Bindings resolve against the synthetic `$__bf_item` range var; don't push
       // a loop param (the param is a pattern, not a name).
-      this.loopBindingStack.push(this.buildDestructureBindingMap(loop, rangeValue))
+      const built = this.buildDestructureBindingMap(loop, rangeValue)
+      this.loopBindingStack.push(built.bindings)
+      this.loopRestExcludeStack.push(built.restExcludes)
       pushedBindingMap = true
       this.loopParamStack.push('')
       if (rangeIndex !== '_') {
@@ -4538,7 +4919,9 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     this.loopScalarItemStack.push(
       this.scalarLiteralLoopGoType(loop.arrayParsed, loop.itemType) !== null,
     )
+    this.loopWrapperStack.push(!!loop.childComponent)
     const children = this.renderChildren(loop.children)
+    this.loopWrapperStack.pop()
     this.loopScalarItemStack.pop()
     // Build the per-item anchor marker while the loop param is still on the
     // stack, so a `bodyIsItemConditional` key expression resolves against the
@@ -4551,7 +4934,10 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       else this.loopVarRefCount.set(v, rc)
     }
     this.loopParamStack.pop()
-    if (pushedBindingMap) this.loopBindingStack.pop()
+    if (pushedBindingMap) {
+      this.loopBindingStack.pop()
+      this.loopRestExcludeStack.pop()
+    }
     this.inLoop = false
 
     // Apply sort if present: wrap the array in a sort pipeline before `range`.
@@ -4607,24 +4993,6 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
     return ''
   }
 
-  /** Find the first component child in a list of nodes. */
-  private findChildComponent(nodes: IRNode[]): IRComponent | null {
-    for (const node of nodes) {
-      if (node.type === 'component') {
-        return node as IRComponent
-      }
-      if (node.type === 'element' && (node as IRElement).children) {
-        const found = this.findChildComponent((node as IRElement).children)
-        if (found) return found
-      }
-      if (node.type === 'fragment' && (node as IRFragment).children) {
-        const found = this.findChildComponent((node as IRFragment).children)
-        if (found) return found
-      }
-    }
-    return null
-  }
-
   /**
    * When `comp`'s JSX children contain template actions (nested components,
    * dynamic text) — i.e. none of the static bake paths in
@@ -4698,13 +5066,15 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
 
     // In Go templates, components are rendered via {{template "name" data}}.
     let templateCall: string
-    if (this.inLoop) {
-      // Loop body component with JSX children: render children through a
-      // companion define so `bf_with_children` injects them at template
-      // execution time. Temporarily exit loop context so nested component calls
-      // (e.g. TableCell inside TableRow) use the normal non-loop rendering path
-      // (`.TableCellSlotN` fields on the wrapper struct), while the loop param
-      // stack stays intact so datum references resolve.
+    if (this.inLoop && (this.loopWrapperStack[this.loopWrapperStack.length - 1] ?? false)) {
+      // Wrapper-slice loop (body IS this component): `.` is the wrapper struct
+      // embedding the child's Props. Loop body component with JSX children:
+      // render children through a companion define so `bf_with_children`
+      // injects them at template execution time. Temporarily exit loop context
+      // so nested component calls (e.g. TableCell inside TableRow) use the
+      // normal non-loop rendering path (`.TableCellSlotN` fields on the
+      // wrapper struct), while the loop param stack stays intact so datum
+      // references resolve.
       const loopBodyDefine = this.queueLoopBodyChildrenDefine(comp)
       if (loopBodyDefine) {
         // Scalar-item loop: feed the body define the wrapper's `.BfLoopItem` (the
@@ -4717,6 +5087,24 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
       } else {
         templateCall = `{{template "${comp.name}" .}}`
       }
+    } else if (this.inLoop && comp.slotId) {
+      // Non-wrapper loop (component nested inside an element item, #2130):
+      // the range iterates the REAL collection, so `.` is the raw datum and
+      // carries none of the child's props. Call through the parent's
+      // once-per-slot instance via the root context (`$` — the define's own
+      // data, i.e. the parent's Props), injecting per-item content through a
+      // loop-body children define executed with the datum (`.`). The shared
+      // instance means identical child scope IDs across rows — the same
+      // contract the wrapper machinery's `bodyChildInstances` already uses.
+      const suffix = slotIdToFieldSuffix(comp.slotId)
+      const loopBodyDefine = this.queueLoopBodyChildrenDefine(comp)
+      templateCall = loopBodyDefine
+        ? `{{template "${comp.name}" (bf_with_children $.${comp.name}${suffix} (bf_tmpl "${loopBodyDefine}" .))}}`
+        : `{{template "${comp.name}" $.${comp.name}${suffix}}}`
+    } else if (this.inLoop) {
+      // Loop-nested component without a slotId: no parent field to route
+      // through — legacy passthrough of the current dot.
+      templateCall = `{{template "${comp.name}" .}}`
     } else if (comp.slotId) {
       // Static children with slotId: unique field name based on slotId.
       const suffix = slotIdToFieldSuffix(comp.slotId)
@@ -4896,16 +5284,30 @@ export class GoTemplateAdapter extends BaseAdapter implements ParsedExprEmitter,
         // Property access through the loop param (`t.attrs`) is already handled
         // by the member-expression path that returns `.Attrs`.
         //
-        // The emit path is wired up but end-to-end fixture coverage is gated on
-        // two harness gaps: (a) `buildGoPropsInit` in `test-render.ts` can't pass
-        // nested-object arrays from JS into the Go input struct, and (b)
-        // `convertInitialValue` returns `nil` for complex literal arrays so
-        // signal-init arrays of objects don't reach the SSR template.
+        // A per-item spread whose operand is a plain object/array field read
+        // (not a destructure-rest binding) is otherwise gated on whether the
+        // enclosing signal's literal initial value bakes at all — see
+        // `parsed-literal-to-go.ts`'s nested object/array property support
+        // (#2087), which lifted the flat-object-only restriction for the
+        // destructure-residual fixtures below.
         const trimmed = value.expr.trim()
         const currentLoopParam = this.loopParamStack[this.loopParamStack.length - 1]
         if (currentLoopParam && trimmed === currentLoopParam) {
           return `{{bf_spread_attrs .}}`
         }
+        // Destructure object-rest spread onto an element (`{...rest}`, #2087
+        // Phase B): `rest` alone would spread the WHOLE item (every field,
+        // including the ones the pattern already destructured out as `id` /
+        // `title`) — route through `bf_omit` instead so the residual excludes
+        // exactly those sibling keys. Only a spread whose expr is the BARE
+        // rest name matches (`isLowerableLoopDestructure`'s admitted shape);
+        // anything else (`{...fn(rest)}`) already refused at the IR gate.
+        const restInfo = this.lookupRestExclude(trimmed)
+        if (restInfo) {
+          const excludeArgs = restInfo.excludeKeys.map(k => JSON.stringify(k)).join(' ')
+          const omitArgs = excludeArgs ? `${restInfo.parent} ${excludeArgs}` : restInfo.parent
+          return `{{bf_spread_attrs (bf_omit ${omitArgs})}}`
+        }
         const goExpr = this.convertExpressionToGo(value.expr)
         // `convertExpressionToGo` already pushes BF101 for unsupported
         // expressions and returns `""`; pass through so the template still