@barefootjs/jsx 0.26.3 → 0.27.0

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

@@ -9,6 +9,7 @@ import type { AttrMeta, IRMetadata } from '../types.ts'
 import { isBooleanAttr } from '../html-constants.ts'
 import type { ClientJsContext } from './types.ts'
 import { toHtmlAttrName, varSlotId, PROPS_PARAM } from './utils.ts'
+import { claimPlanLiteral, claimWriterVarName, type ClaimSlotSpec } from './control-flow/stringify/claim-plan.ts'
 import { createTemplateAwareStringProtector } from './html-template.ts'
 import { datePlugin, DATE_METHODS } from '../date-lowering.ts'
 import { toLocaleDatePlugin, foldedArgToClientJs } from '../to-locale-date-lowering.ts'
@@ -303,24 +304,44 @@ export function emitDynamicTextUpdates(lines: string[], ctx: ClientJsContext): v
     const normalElems = elems.filter(e => !e.insideConditional)
 
     if (normalElems.length > 0 || conditionalElems.length > 0) {
-      // Persistent slot trackers for non-conditional elements. `__bfText`
-      // returns the node now occupying the slot; a JSX-valued expression
-      // (`{themeLogo(id)}`) replaces the text node with a live element, so
-      // the next reactive run must operate on that element, not the stale
-      // text node (#1663). Primitive values keep the same text node.
-      for (const elem of normalElems) {
-        const v = varSlotId(elem.slotId)
-        lines.push(`  let __anchor_${v} = _${v}`)
-      }
       const __textSlot = (normalElems[0] ?? conditionalElems[0])?.slotId
+
+      // Non-conditional elements: ONE claimed 'markup' writer covering every
+      // slot this expression feeds (slot unification A3, row-level claim at
+      // `__scope` — spec/slot-unification.md §3(a)/§5-A3). 'markup' (not
+      // 'text') because the value may be a live Node (e.g. a JSX-returning
+      // call like `{themeLogo(id)}`) — the writer splices a Node in by
+      // identity, exactly the contract `__bfText` used to provide (#1663).
+      let writer = ''
+      if (normalElems.length > 0) {
+        const slots: ClaimSlotSpec[] = normalElems.map(elem => ({ id: elem.slotId, kind: 'markup', path: [] }))
+        writer = claimWriterVarName(slots, varSlotId)
+        lines.push(`  const ${writer} = lazySlots(__scope, ${claimPlanLiteral(slots)})`)
+      }
+
       lines.push(`  createEffect(() => {`)
       if (normalElems.length > 0) {
         // Expression is always evaluated for non-conditional elements
         lines.push(`    const __val = ${expr}`)
+        // `escapeTextOrNode`: `writeMarkup` inserts a string via
+        // `innerHTML =`, which — unlike the plain `Text.nodeValue =`
+        // assignment the initial SSR/CSR TEMPLATE's `escapeText(${expr})`
+        // was standing in for — DOES interpret HTML, so a raw un-escaped
+        // string here is an injection/byte-parity gap; a live Node (this
+        // expression may return one) must pass through untouched instead.
         for (const elem of normalElems) {
-          const v = varSlotId(elem.slotId)
-          lines.push(`    __anchor_${v} = __bfText(__anchor_${v}, __val)`)
+          lines.push(`    ${writer}('${elem.slotId}', escapeTextOrNode(__val))`)
         }
+        // Conditional elements: deferred from slot unification A3 — see
+        // `__bfText`'s docstring for why. `insert()` may swap the branch's
+        // DOM independently of this effect's own reruns, and a cached claim
+        // door's dedup state would go stale across that swap (unlike the
+        // 'text'-kind conditional cases elsewhere in the compiler, this
+        // slot's value may be a live Node, so it can't reuse the "just
+        // re-claim fresh every run" trick those use — a fresh 'markup'
+        // claim's dedup state always starts empty, so re-claiming per-run
+        // would throw away the unchanged-value skip on every single run).
+        // Keeps `$t` + `__bfText`.
         for (const elem of conditionalElems) {
           const v = varSlotId(elem.slotId)
           lines.push(`    const [__el_${v}] = $t(__scope, '${elem.slotId}')`)
@@ -348,13 +369,28 @@ export function emitDynamicTextUpdates(lines: string[], ctx: ClientJsContext): v
   }
 }
 
-/** Emit createEffect blocks for client-only expressions using comment markers. */
+/**
+ * Emit createEffect blocks for `@client` expressions. Slot unification A3:
+ * these are ordinary claimed 'text' slots now (never Node-valued — `@client`
+ * only ever evaluates a plain expression), one writer per slot at `__scope`,
+ * replacing `updateClientMarker`'s full-tree rescan + zero-width-space
+ * managed-node marker (no longer needed: a claimed Text node's identity is
+ * already known, so there's nothing to disambiguate from other content).
+ */
 export function emitClientOnlyExpressions(lines: string[], ctx: ClientJsContext): void {
   for (const elem of ctx.clientOnlyElements) {
+    // Slot unification Step B: `elem.elidedPath`, when present, was proven
+    // safe by `client-only-elision.ts` before this pass ran — use the real
+    // position-based path and skip the marker-scan fallback entirely.
+    const slots: ClaimSlotSpec[] = elem.elidedPath
+      ? [{ id: elem.slotId, kind: 'text', path: elem.elidedPath, markerless: true }]
+      : [{ id: elem.slotId, kind: 'text', path: [] }]
+    const writer = claimWriterVarName(slots, varSlotId)
     lines.push(`  // @client: ${elem.slotId}`)
+    lines.push(`  { const ${writer} = lazySlots(__scope, ${claimPlanLiteral(slots)})`)
     lines.push(`  createEffect(() => {`)
-    lines.push(`    updateClientMarker(__scope, '${elem.slotId}', ${elem.expression})`)
-    lines.push(`  }${bindingIdArg(ctx, elem.slotId)})`)
+    lines.push(`    ${writer}('${elem.slotId}', ${elem.expression})`)
+    lines.push(`  }${bindingIdArg(ctx, elem.slotId)}) }`)
     lines.push('')
   }
 }

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

@@ -2,7 +2,7 @@
  * IR → HTML template string generation and validation.
  */
 
-import type { AttrValue, IRAttribute, IRNode, IRProp, MapCallbackPreamble } from '../types.ts'
+import type { AttrValue, FlatMapCallback, IRAttribute, IRNode, IRProp, MapCallbackPreamble } from '../types.ts'
 import { isBooleanAttr } from '../html-constants.ts'
 import { toHtmlAttrName, attrValueToString, quotePropName, PROPS_PARAM, DATA_BF_PH, keyAttrName, loopStartMarker, loopEndMarker, loopItemMarker, freeIdsFromRefs, setIntersects, wrapExprWithLoopParams } from './utils.ts'
 import type { LoopParamSpec } from './utils.ts'
@@ -126,7 +126,11 @@ export function createTemplateAwareStringProtector(): {
   return { protect, restore, replaceProtectedCall }
 }
 
-const VOID_ELEMENTS = new Set([
+// Exported (not just module-local) so `client-only-elision.ts` (slot
+// unification Step B) can reuse the exact same void-element list when it
+// walks the IR tree computing markerless-eligible child-index paths —
+// duplicating this list would risk the two walks silently drifting apart.
+export const VOID_ELEMENTS = new Set([
   'area', 'base', 'br', 'col', 'embed', 'hr', 'img',
   'input', 'link', 'meta', 'param', 'source', 'track', 'wbr',
 ])
@@ -276,9 +280,14 @@ function templateAttrExpr(attrName: string, valExpr: string, presenceOrUndefined
   // `data-key` / `data-key-N` is a reconciliation contract — every loop item
   // must carry one. Emit unconditionally; if the user passes `key={undefined}`
   // we want it to surface as `data-key="undefined"` (and ultimately a runtime
-  // assertion in mapArray) rather than silently fall back to "no key".
+  // assertion in mapArray) rather than silently fall back to "no key" —
+  // `escapeAttr(undefined)` stringifies to exactly that. The value is escaped
+  // like every other dynamic attribute: SSR adapters escape it (their
+  // template engines do), so an unescaped `"` in a key — surfaced by the
+  // flatmap-expression-body fixture's adversarial keys — corrupted the
+  // client-assembled HTML and diverged from the SSR bytes.
   if (attrName === 'data-key' || attrName.startsWith('data-key-')) {
-    return `${attrName}="\${${valExpr}}"`
+    return `${attrName}="\${${escapeAttrValueExpr(valExpr)}}"`
   }
   return `\${(${valExpr}) != null ? '${attrName}="' + ${escapeAttrValueExpr(valExpr)} + '"' : ''}`
 }
@@ -575,6 +584,12 @@ export function renderPreamble(
     transformJs?: (text: string) => string
     /** Context-appropriate leaf renderer (an irToHtmlTemplate variant). */
     renderLeaf: (ir: IRNode) => string
+    /**
+     * When true, `renderLeaf` output is spliced verbatim — the renderer
+     * supplies its own delimiters (e.g. the flatMap descriptor form
+     * `({ k, h })`). Default wraps each leaf in a template literal.
+     */
+    rawLeaf?: boolean
   },
 ): string {
   let out = ''
@@ -582,6 +597,8 @@ export function renderPreamble(
     if (seg.kind === 'js') {
       const text = opts.textVariant === 'template' ? (seg.templateText ?? seg.text) : seg.text
       out += opts.transformJs ? opts.transformJs(text) : text
+    } else if (opts.rawLeaf) {
+      out += opts.renderLeaf(escapeLeafTextExpressions(seg.ir))
     } else {
       out += '`' + opts.renderLeaf(escapeLeafTextExpressions(seg.ir)) + '`'
     }
@@ -589,6 +606,96 @@ export function renderPreamble(
   return out
 }
 
+/**
+ * Project a flatMap segment leaf's `key={...}` attribute into a runtime key
+ * expression, or `null` when the leaf declares none. Template-literal keys
+ * (`key={\`${it.id}:${tag}\`}`) are first-class here — unlike the loop-level
+ * `extractLoopKey`, the expression is evaluated inside the flatMap body where
+ * the callback params are in scope, so any expression form works.
+ */
+export function flatMapLeafKeyExpr(ir: IRNode): string | null {
+  if (ir.type !== 'element') return null
+  const keyAttr = ir.attrs.find((a) => a.name === 'key')
+  if (!keyAttr) return null
+  switch (keyAttr.value.kind) {
+    case 'expression':
+      return `(${keyAttr.value.expr})`
+    case 'literal':
+      return JSON.stringify(keyAttr.value.value)
+    case 'template':
+      return attrValueToString(keyAttr.value)
+    default:
+      return null
+  }
+}
+
+/** Copy of `ir` with the loop `key` attribute removed (element leaves only). */
+function stripLeafKeyAttr(ir: IRNode): IRNode {
+  if (ir.type !== 'element') return ir
+  return { ...ir, attrs: ir.attrs.filter((a) => a.name !== 'key') }
+}
+
+/**
+ * Render a `FlatMapCallback` as the CLIENT-SIDE descriptor body for
+ * `mapArray` (the reconciliation twin of the string-template rendering in
+ * `irToHtmlTemplate`'s `'loop'` case). Each JSX leaf becomes
+ * `({ k: <keyExpr>, h: \`<html>\` })` — the flatMap flattens descriptors,
+ * `mapArray` keys on `d.k` (index fallback), and the emitted renderItem
+ * builds/patches the leaf element from `d.h`.
+ *
+ * Runs in the init scope where the loop SOURCE items are plain values (the
+ * flatMap executes inside the `mapArray` accessor, BEFORE per-item signals
+ * exist), so neither js segments nor leaf HTML get the accessor wrap — refs
+ * stay `t.title`, not `t().title`. `data-key` is deliberately NOT emitted in
+ * the leaf HTML: reconciliation identity is stamped by `mapArray` via
+ * `setAttribute`, matching the SSR side (which never emits it for flatMap
+ * leaves).
+ */
+export function renderFlatMapClientBody(
+  cb: Pick<FlatMapCallback, 'segments'>,
+  restSpreadNames?: Set<string>,
+): string {
+  return renderPreamble(cb, {
+    textVariant: 'client',
+    rawLeaf: true,
+    renderLeaf: (ir) => {
+      const key = flatMapLeafKeyExpr(ir)
+      const html = irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, 1, undefined, undefined, true)
+      return `({ k: ${key ?? 'undefined'}, h: \`${html}\` })`
+    },
+  })
+}
+
+/** True when any segment leaf declares a `key` — drives the mapArray keyFn. */
+export function flatMapCallbackHasKeyedLeaf(cb: Pick<FlatMapCallback, 'segments'>): boolean {
+  return cb.segments.some((s) => s.kind === 'jsx' && flatMapLeafKeyExpr(s.ir) !== null)
+}
+
+/**
+ * Synthesize the client descriptor body for a flatMap PROJECTION loop —
+ * one whose only child is a nested `IRLoop` lowered from
+ * `flatMap(it => it.tags.map(tag => <li/>))`. The neutral IR is the single
+ * carrier: SSR adapters templatize the nested loop natively, and this
+ * derives the `mapArray` accessor's flatten projection from the SAME inner
+ * loop — `<chained-inner>.map((tag, i) => ({ k: <inner.key>, h: `<leaf>` }))`.
+ * Runs in the accessor context (plain source items, no per-item signals),
+ * so leaf refs stay unwrapped. Leaf `key` attrs were already stripped at IR
+ * build (`stripLoopLeafKeyAttrs`); the inner loop's `key` FIELD supplies
+ * `k`.
+ */
+export function renderFlatMapProjectionClientBody(
+  inner: Extract<IRNode, { type: 'loop' }>,
+  restSpreadNames?: Set<string>,
+): string {
+  const chained = applyLoopChain(inner)
+  const params = inner.index ? `(${inner.param}, ${inner.index})` : `(${inner.param})`
+  const key = inner.key ? `(${inner.key})` : 'undefined'
+  const html = inner.children
+    .map((c) => irToHtmlTemplate(escapeLeafTextExpressions(c), restSpreadNames, 1, undefined, undefined, true))
+    .join('')
+  return `${chained}.map(${params} => ({ k: ${key}, h: \`${html}\` }))`
+}
+
 /**
  * SSR/CSR escaping parity for preamble leaves, decided once at the door: a
  * JSX-runtime SSR adapter renders the leaf's raw JSX and auto-escapes text
@@ -691,6 +798,16 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
 
     case 'expression': {
       if (node.expr === 'null' || node.expr === 'undefined') return ''
+      // Slot unification Step B (`markerless`, decided once by
+      // `client-only-elision.ts` before this CSR pass runs): drop the
+      // marker pair and fall through to the same bare `${...}` shape the
+      // no-slotId branch below already uses — `elidedPath` (not this
+      // string) is what the claim plan resolves against, so no marker
+      // anchor is needed here at all.
+      if (node.markerless) {
+        const bare = wrapInterpolation(wrapExpr(node.expr))
+        return `\${${bare}}`
+      }
       const inner = wrapInterpolation(wrapExpr(node.expr))
       // Stage 3 / D4 — an element-array child ({out}) built by an arbitrary
       // .map() preamble is an array of HTML strings; join it rather than let
@@ -805,8 +922,8 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       // (Go's `bf_sort`, etc.) applied the sort separately and
       // hydration only needed to match, but broken on Hono / CSR
       // where the template is the only source of truth. The chain
-      // mirrors `buildChainedArrayExpr` so reconcileList sees the
-      // same array shape this template emits.
+      // mirrors `buildChainedArrayExpr` so mapArray/mapArrayAnchored sees
+      // the same array shape this template emits.
       const rawChainedArray = applyLoopChain(node)
       const { array: iterArray, callbackParam } = applyIterationShape(node, rawChainedArray, indexParam)
       const wrappedArray = wrapExpr(iterArray)
@@ -816,8 +933,12 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       if (node.flatMapCallback) {
         // Complex flatMap: the body is structured segments, rendered through
         // the same single door as map preambles.
+        // Leaf `key` is stripped from the string form: SSR (Hono rawBody)
+        // never emits data-key for flatMap leaves, and reconciliation
+        // identity is stamped by mapArray via setAttribute — emitting it
+        // here was the CSR/SSR data-key asymmetry (unescaped, client-only).
         const body = renderPreamble(node.flatMapCallback, {
-          renderLeaf: (ir) => irToHtmlTemplate(ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop),
+          renderLeaf: (ir) => irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop),
         })
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
       } else if (node.preamble) {
@@ -1013,7 +1134,9 @@ export interface SkeletonSlotPaths {
  * the loop keeps its hoisted-clone fast path, but every slot lookup falls
  * back to `qsa`/`$t`.
  */
-const SKELETON_PATH_HAZARD_TAGS = new Set([
+// Exported for reuse by `client-only-elision.ts` (Step B) — same hazard
+// class, same reasoning, must never drift out of sync with a second copy.
+export const SKELETON_PATH_HAZARD_TAGS = new Set([
   'table', 'thead', 'tbody', 'tfoot', 'caption', 'colgroup', 'col',
   'select', 'optgroup',
   'p',
@@ -1029,7 +1152,7 @@ const SKELETON_PATH_HAZARD_TAGS = new Set([
  * `<dt>` closes the `<dt>`). A skeleton hitting this bails on path
  * computation entirely (see `SKELETON_PATH_HAZARD_TAGS` doc).
  */
-const SKELETON_PATH_FORCE_CLOSE_GROUPS: ReadonlyArray<ReadonlySet<string>> = [
+export const SKELETON_PATH_FORCE_CLOSE_GROUPS: ReadonlyArray<ReadonlySet<string>> = [
   new Set(['a']),
   new Set(['button']),
   new Set(['form']),
@@ -1039,7 +1162,7 @@ const SKELETON_PATH_FORCE_CLOSE_GROUPS: ReadonlyArray<ReadonlySet<string>> = [
   new Set(['li']),
 ]
 
-function skeletonForceCloseGroup(tag: string): number {
+export function skeletonForceCloseGroup(tag: string): number {
   return SKELETON_PATH_FORCE_CLOSE_GROUPS.findIndex(group => group.has(tag))
 }
 
@@ -1097,7 +1220,7 @@ function walkSkeletonPathNode(
 }
 
 /** True if `children` (already flattened) contains anything the HTML parser would foster-parent out of a `<tr>`. */
-function hasForeignTableRowContent(children: readonly IRNode[]): boolean {
+export function hasForeignTableRowContent(children: readonly IRNode[]): boolean {
   for (const child of children) {
     if (child.type === 'text') {
       if (child.value.trim() !== '') return true
@@ -1111,7 +1234,7 @@ function hasForeignTableRowContent(children: readonly IRNode[]): boolean {
 }
 
 /** Splice fragment children inline — a fragment contributes no DOM node of its own. */
-function flattenSkeletonChildren(children: readonly IRNode[]): IRNode[] {
+export function flattenSkeletonChildren(children: readonly IRNode[]): IRNode[] {
   const out: IRNode[] = []
   for (const child of children) {
     if (child.type === 'fragment') {
@@ -1263,7 +1386,8 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
       let mapExpr: string
       if (node.flatMapCallback) {
         const body = renderPreamble(node.flatMapCallback, {
-          renderLeaf: (ir) => irToPlaceholderTemplate(ir, restSpreadNames, loopDepth + 1, loopParams),
+          // Leaf `key` stripped — see the irToHtmlTemplate site above.
+          renderLeaf: (ir) => irToPlaceholderTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams),
         })
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
       } else if (node.preamble) {
@@ -2214,7 +2338,11 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
       if (node.clientOnly && node.slotId) {
-        return `<!--bf-client:${node.slotId}--><!--/-->`
+        // Ordinary claimed 'text' slot pair (slot unification A3) — matches
+        // the SSR adapters' `renderExpression` byte-for-byte (byte parity):
+        // empty at CSR mount too, since the expression is evaluated only
+        // once init's createEffect runs, same as the SSR case.
+        return `<!--bf:${node.slotId}--><!--/-->`
       }
       {
         const transformed = transformExpr(node.expr, node.templateExpr)
@@ -2386,7 +2514,8 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         const body = renderPreamble(node.flatMapCallback, {
           textVariant: 'template',
           transformJs: (t) => applyPropsRewrite(t, propsObjectName ?? null),
-          renderLeaf: (ir) => recurseInLoopBody(ir),
+          // Leaf `key` stripped — see the irToHtmlTemplate site above.
+          renderLeaf: (ir) => recurseInLoopBody(stripLeafKeyAttr(ir)),
         })
         mapExpr = `\${${iterArrayExpr}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
       } else if (node.preamble) {

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

@@ -8,13 +8,16 @@ import { isClientBuiltinName } from '../builtins.ts'
 // All exports from @barefootjs/client/runtime that may be used in generated code
 export const RUNTIME_IMPORT_CANDIDATES = [
   'createSignal', 'createMemo', 'createEffect', 'onCleanup', 'onMount',
-  'hydrate', 'insert', 'reconcileElements', 'getLoopChildren', 'getLoopNodes', 'mapArray', 'mapArrayAnchored', 'createDisposableEffect',
-  'createComponent', 'renderChild', 'registerComponent', 'registerTemplate', 'initChild', 'upsertChild', 'updateClientMarker',
+  'hydrate', 'insert', 'getLoopChildren', 'getLoopNodes', 'mapArray', 'mapArrayAnchored', 'patchLeaf', 'createDisposableEffect',
+  'createComponent', 'renderChild', 'registerComponent', 'registerTemplate', 'initChild', 'upsertChild',
   'createPortal',
   'provideContext', 'createContext', 'useContext',
-  'forwardProps', 'applyRestAttrs', 'splitProps', 'spreadAttrs', 'styleToCss', 'escapeAttr', 'escapeText',
+  'forwardProps', 'applyRestAttrs', 'splitProps', 'spreadAttrs', 'styleToCss', 'escapeAttr', 'escapeText', 'escapeTextOrNode',
   'qsa', 'qsaItem', 'qsaChildScope', 'qsaChildScopes', 'upsertChildItem', '__slot', '__bfSlot', '__bfText',
-  'tAfter',
+  // Claim-plan interpreter (slot unification A2/A3, spec/slot-unification.md)
+  // — the "one claim mechanism" that replaced `patchSlotRange` and
+  // `updateClientMarker` (both deleted) as the content-slot update door.
+  'claimSlots', 'lazySlots',
   // Profile mode (#1690, SR3) — turn-boundary markers around event handlers.
   'beginTurn', 'endTurn',
   // Catalogued `Date` lowering (#2274/#2292) — the client counterpart to

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

@@ -570,6 +570,13 @@ export function collectLoopChildReactiveTexts(
     ...stopAt<boolean>('loop', 'async', 'ifStatement'),
     expression: ({ node: n, scope: insideConditional }) => {
       if (!n.slotId) return
+      // #2389 — a preamble-patched region (see `IRLoop.preambleRegions`) has
+      // its own claimed 'markup'-slot effect (`preambleRegions` in the
+      // client-JS loop plan; slot unification A3, `@barefootjs/client/
+      // runtime/claim-slots.ts`); it must never ALSO become a `reactiveTexts`
+      // entry, which would patch it via `.textContent` and corrupt markup
+      // (a `joinArrayChild` region's value is raw HTML, not text).
+      if (n.preambleRegion) return
       const originFreeIds = freeIdsFromRefs(n.origin?.freeRefs)
       const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds)
       // Include if expression reads signals OR references the loop parameter

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

@@ -23,6 +23,7 @@ import type {
   TypeInfo,
   TypeDefinition,
   MapCallbackPreamble,
+  PreambleRegionSource,
 } from '../types.ts'
 import type { CsrInlinabilityMap } from './csr-substitute.ts'
 import type { SkeletonSlotPaths } from './html-template.ts'
@@ -254,7 +255,7 @@ export interface LoopCore {
   /**
    * Unique id for this loop's `<!--bf-loop:<id>--> ... <!--bf-/loop:<id>-->`
    * marker pair, threaded from `IRLoop.markerId`. Each `mapArray()` /
-   * `reconcileElements()` call passes this id so sibling loops under the
+   * `mapArrayAnchored()` call passes this id so sibling loops under the
    * same parent reconcile their own range (#1087).
    */
   markerId: string
@@ -310,6 +311,29 @@ export interface LoopCore {
    * `IRLoop.objectIteration`.
    */
   objectIteration?: 'entries' | 'keys' | 'values'
+
+  /**
+   * Client-side descriptor body for a flatMap loop carried as structured
+   * segments (`IRLoop.flatMapCallback`). `body` is the callback body
+   * rendered so each JSX leaf becomes a `({ k, h })` descriptor
+   * (`renderFlatMapClientBody`); the plan builder wires
+   * `mapArray(() => <chained>.flatMap(<params> => <body>), …)` so the
+   * runtime reconciles the FLATTENED leaves — never the un-flattened
+   * source items (which loses leaves at hydration and crashes on adds
+   * against an empty item template). `keyed` is true when any leaf
+   * declares a `key`, driving the `d.k`-based keyFn.
+   */
+  flatMapClient?: { params: string; body: string; keyed: boolean }
+
+  /**
+   * Loop-body expression children classified as preamble-patched regions
+   * (#2389), threaded from `IRLoop.preambleRegions`. Consumed only by the
+   * top-level and branch **plain** loop-plan builders (`build-loop.ts`,
+   * `build-branch-loop.ts`) — the composite / component / static / anchored
+   * shapes leave this unconsumed (stale — same pre-existing freeze, not a
+   * new regression) pending a follow-up.
+   */
+  preambleRegions?: readonly PreambleRegionSource[]
 }
 
 /**
@@ -585,7 +609,7 @@ export interface TopLevelLoop extends LoopCore {
   // Per-item bindings (events / reactiveAttrs / reactiveTexts / refs / conditionals)
   // now live on `LoopCore.bindings` — see issue #1244 §B.
   isStaticArray: boolean // True if array is a static prop (not a signal)
-  useElementReconciliation?: boolean // True: reconcileElements + composite rendering (native root with child components)
+  useElementReconciliation?: boolean // True: mapArray/mapArrayAnchored + composite rendering (native root with child components)
   /** Inner loop metadata for composite element reconciliation (array, param, key, container) */
   innerLoops?: NestedLoop[]
   /** Offset of this loop's items past its preceding container siblings (#1693). */
@@ -630,6 +654,14 @@ export interface ReactiveAttribute extends AttrMeta {
 export interface ClientOnlyElement {
   slotId: string
   expression: string
+  /**
+   * Slot unification Step B (`spec/slot-unification.md` §3(b), §5 Step B):
+   * copied from `IRExpression.elidedPath` (`client-only-elision.ts`) when
+   * the compiler proved this slot's marker pair can be elided. Absent
+   * (`undefined`) is always safe — the claim plan falls back to `path: []`
+   * / marker-based resolution exactly as before Step B.
+   */
+  elidedPath?: readonly number[]
 }
 
 

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

@@ -180,7 +180,7 @@ export function applyObjectIterationWrap(
 }
 
 /**
- * Build the chained array expression for reconcileList. Thin
+ * Build the chained array expression for mapArray/mapArrayAnchored. Thin
  * adapter over `buildLoopChainExpr` that unpacks the collected
  * `TopLevelLoop` / `BranchLoop` shape into the primitive inputs.
  * Branch loops carry the same `filterPredicate` / `sortComparator`