@barefootjs/jsx 0.29.0 → 0.30.2

package/src/ir-to-client-js/control-flow/stringify/lazy-row.ts

@@ -70,7 +70,12 @@ import {
   emitTemplateCloneInline,
   hoistedCloneExpr,
 } from './template-parse.ts'
-import type { LazyRowAttrBinding, LazyRowPlanData, LazyRowTextBinding } from '../plan/build-lazy-row.ts'
+import type {
+  LazyRowAttrBinding,
+  LazyRowConditionalBinding,
+  LazyRowPlanData,
+  LazyRowTextBinding,
+} from '../plan/build-lazy-row.ts'
 
 export interface StringifyLazyRowOptions {
   /** Indent of the `mapArrayLazy(` line itself. */
@@ -94,9 +99,11 @@ export function stringifyLazyRowLoop(lines: string[], o: StringifyLazyRowOptions
   const { indent, lazyRow, paramHead } = o
   const mid = o.markerId.replace(/[^A-Za-z0-9_$]/g, '_')
   const tplVar = `__tpl_${mid}`
-  const claimVar = `__lzc_${mid}`
   const hasRefs = lazyRow.attrSlotIds.length > 0 || lazyRow.texts.length > 0
-  const hasBindings = lazyRow.attrs.length > 0 || lazyRow.texts.length > 0
+  // Conditionals count: `createRow` seeds their dedup boolean into `__l`, so a
+  // row whose ONLY reactive thing is a conditional still needs `__l` declared.
+  const hasBindings =
+    lazyRow.attrs.length > 0 || lazyRow.texts.length > 0 || lazyRow.conditionals.length > 0
   // ONE per-loop door decision (see `refParts`): the read-capable claim, or
   // today's write-only writer. Never decided per binding — the door is
   // allocated once per ROW.
@@ -165,28 +172,17 @@ export function stringifyLazyRowLoop(lines: string[], o: StringifyLazyRowOptions
     }
   }
 
-  // Lazy ref claim for ADOPTED (SSR) rows: one scan inside that row, cached
-  // on `entry.refs`. Shared by applyItem and applyOuter so a row claims once.
-  //
-  // The text door slot is left EMPTY here and filled by the first content
-  // write (`doorAccess`). An adopted row is claimed by whichever of
-  // applyItem/applyOuter touches it first, and an `applyOuter` that only
-  // drives ATTRIBUTES never reads or writes a content slot — so building the
-  // door in this function spends one closure per row of the list on something
-  // that stays unused until (and unless) that row's item changes. Deferring
-  // is confined to the adopted path on purpose: `createRow` writes every text
-  // immediately, so its door is used on the same tick it is built and there
-  // is nothing to defer (see the `deferDoor` note on `refParts`).
-  if (hasRefs) {
-    // With the door deferred, the ELEMENT refs are the only parts that read the
-    // row root — so a text-only row (no reactive-attr slot) claims to a bare
-    // `[null]` and the `__el` binding would be dead. `parts` decides, rather
-    // than a second predicate that could drift from `refParts`.
-    const parts = refParts(lazyRow, '__el', null, adoptedPlanVar, true)
-    lines.push(`${indent}const ${claimVar} = (__e) => {`)
-    if (parts.some(p => p.includes('__el'))) lines.push(`${indent}  const __el = __e.primaryEl`)
-    lines.push(`${indent}  return [${parts.join(', ')}]`)
-    lines.push(`${indent}}`)
+  // Hoisted arm templates, one pair per conditional. Both arms are static by
+  // construction (`analyzeLazyConditional`), so each is parsed ONCE per loop and
+  // cloned on a flip — a per-row `innerHTML` parse would undo the point of
+  // driving the swap from the loop level. The comparison the seed run makes is
+  // against `content.firstElementChild.outerHTML`, i.e. the browser's OWN
+  // serialization of the same markup, so it cannot false-mismatch on attribute
+  // order or quoting the way comparing against the authored string would.
+  for (const c of lazyRow.conditionals) {
+    const v = condVars(mid, c.slotId)
+    emitHoistedTemplateDecl(lines, indent, v.trueTpl, c.whenTrueHtml)
+    emitHoistedTemplateDecl(lines, indent, v.falseTpl, c.whenFalseHtml)
   }
 
   const call = `mapArrayLazy(() => ${o.arrayExpr}, ${o.containerVar}, ${o.keyFn}, {`
@@ -200,6 +196,9 @@ export function stringifyLazyRowLoop(lines: string[], o: StringifyLazyRowOptions
   // interpolates the per-row template, which reads the param for at least
   // the `data-key` attribute.
   lines.push(`${b2}const ${paramHead} = () => __e.item`)
+  // The row's `.map()` callback preamble, before the clone: a non-hoisted
+  // per-row template interpolates values the preamble declares.
+  if (lazyRow.preambleStatements) lines.push(`${b2}${lazyRow.preambleStatements}`)
   const cloneExpr = useHoisted
     ? hoistedCloneExpr(tplVar, o.skeletonTemplate!)
     : `(() => { ${emitTemplateCloneInline(o.template)} })()`
@@ -213,31 +212,42 @@ export function stringifyLazyRowLoop(lines: string[], o: StringifyLazyRowOptions
     const createDoor = `__r[${lazyRow.writerIndex}]`
     for (const t of lazyRow.texts) emitTextBinding(lines, b2, t, createDoor, 'create', rwDoor)
   }
+  for (const c of lazyRow.conditionals) emitConditional(lines, b2, mid, c, 'create')
   lines.push(`${b2}return __el`)
   lines.push(`${b1}},`)
 
   // --- applyItem ---------------------------------------------------------
   const itemAttrs = lazyRow.attrs.filter(a => a.readsItem)
   const itemTexts = lazyRow.texts.filter(t => t.readsItem)
-  if (itemAttrs.length === 0 && itemTexts.length === 0) {
+  const itemConds = lazyRow.conditionals.filter(c => c.readsItem)
+  if (itemAttrs.length === 0 && itemTexts.length === 0 && itemConds.length === 0) {
     lines.push(`${b1}applyItem: () => {},`)
   } else {
     lines.push(`${b1}applyItem: (__e) => {`)
     lines.push(`${b2}const ${paramHead} = () => __e.item`)
-    lines.push(`${b2}const __r = __e.refs ?? (__e.refs = ${claimVar}(__e))`)
+    lines.push(`${b2}const __r = __e.refs ?? (__e.refs = [])`)
     lines.push(`${b2}const __l = __e.last ?? (__e.last = [])`)
+    // Re-run the preamble only when a binding in THIS body reads a local it
+    // declares (#2447 follow-up). `mapArrayLazy` wraps `applyItem` in
+    // `untrack()`, so a signal read inside the preamble subscribes nothing
+    // here — the subscription is `applyOuter`'s job.
+    if (lazyRow.itemNeedsPreamble && lazyRow.preambleStatements) {
+      lines.push(`${b2}${lazyRow.preambleStatements}`)
+    }
     for (const a of itemAttrs) emitAttrBinding(lines, b2, a, 'item')
     if (itemTexts.length > 0) {
       lines.push(`${b2}const __d = ${doorAccess(lazyRow, lazyRow.writerIndex, adoptedPlanVar)}`)
       for (const t of itemTexts) emitTextBinding(lines, b2, t, '__d', 'item', rwDoor)
     }
+    for (const c of itemConds) emitConditional(lines, b2, mid, c, 'item')
     lines.push(`${b1}},`)
   }
 
   // --- applyOuter (only when some binding is outer-involving) -------------
   const outerAttrs = lazyRow.attrs.filter(a => a.readsOuter)
   const outerTexts = lazyRow.texts.filter(t => t.readsOuter)
-  if (outerAttrs.length > 0 || outerTexts.length > 0) {
+  const outerConds = lazyRow.conditionals.filter(c => c.readsOuter)
+  if (outerAttrs.length > 0 || outerTexts.length > 0 || outerConds.length > 0) {
     const b3 = `${indent}      `
     lines.push(`${b1}applyOuter: (__es, __seed) => {`)
     // Prime the outer reads so this ONE loop-level effect subscribes even
@@ -245,13 +255,20 @@ export function stringifyLazyRowLoop(lines: string[], o: StringifyLazyRowOptions
     for (const g of lazyRow.outerPrimeGetters) lines.push(`${b2}${g}()`)
     lines.push(`${b2}for (const __e of __es) {`)
     lines.push(`${b3}const ${paramHead} = () => __e.item`)
-    lines.push(`${b3}const __r = __e.refs ?? (__e.refs = ${claimVar}(__e))`)
+    lines.push(`${b3}const __r = __e.refs ?? (__e.refs = [])`)
     lines.push(`${b3}const __l = __e.last ?? (__e.last = [])`)
+    // Per ENTRY, not once for the batch: the preamble reads the item, so its
+    // locals differ per row. The outer signals it reads are already primed
+    // above, so this effect subscribes even when `__es` is empty.
+    if (lazyRow.outerNeedsPreamble && lazyRow.preambleStatements) {
+      lines.push(`${b3}${lazyRow.preambleStatements}`)
+    }
     for (const a of outerAttrs) emitAttrBinding(lines, b3, a, 'outer')
     if (outerTexts.length > 0) {
       lines.push(`${b3}const __d = ${doorAccess(lazyRow, lazyRow.writerIndex, adoptedPlanVar)}`)
       for (const t of outerTexts) emitTextBinding(lines, b3, t, '__d', 'outer', rwDoor)
     }
+    for (const c of outerConds) emitConditional(lines, b3, mid, c, 'outer')
     lines.push(`${b2}}`)
     lines.push(`${b1}},`)
   }
@@ -260,9 +277,10 @@ export function stringifyLazyRowLoop(lines: string[], o: StringifyLazyRowOptions
 }
 
 /**
- * The `entry.refs` array contents: one element ref per reactive-attr slot
- * (in `attrSlotIds` order), then — when the row has text slots — the
- * claimed-slot door at `writerIndex`.
+ * The `entry.refs` array `createRow` seeds: one element ref per reactive-attr
+ * slot (in `attrSlotIds` order), then — when the row has text slots — the
+ * claimed-slot door at `writerIndex`. Fresh-clone context only; an ADOPTED row
+ * starts empty and fills each slot on demand (`elementAccess` / `doorAccess`).
  *
  * **Which door (per LOOP, never per binding).** `lazySlots` returns a bare
  * write function; `lazyClaimSlots` returns the `{ write, read }` pair over
@@ -312,7 +330,6 @@ function refParts(
   elVar: string,
   skeletonPaths: SkeletonSlotPaths | null,
   planVar: string | null,
-  deferDoor = false,
 ): string[] {
   const parts: string[] = []
   for (const slotId of lazyRow.attrSlotIds) {
@@ -320,11 +337,31 @@ function refParts(
     parts.push(path ? pathExpr(elVar, path) : `qsa(${elVar}, '[bf="${slotId}"]')`)
   }
   if (lazyRow.texts.length > 0) {
-    parts.push(deferDoor ? 'null' : `${doorCtor(lazyRow)}(${elVar}, ${planVar})`)
+    parts.push(`${doorCtor(lazyRow)}(${elVar}, ${planVar})`)
   }
   return parts
 }
 
+/**
+ * How an ADOPTED row's binding reaches its element ref: claim THIS slot, and
+ * only this slot, on first use.
+ *
+ * The previous shape claimed the whole row in one closure (`__lzc_<mid>`),
+ * which meant an `applyOuter` driving ONE attribute still ran a `qsa` scan for
+ * every OTHER reactive-attr slot in the row — on every row, at hydration. The
+ * `in` test (not `??`) is what makes the cache honest: `qsa` answers `null` for
+ * a slot it cannot find, and `null` is a real cached answer — the `in` test
+ * treats it as one and never scans again, where a `??`-guarded cache would
+ * re-scan that slot on every tick forever.
+ *
+ * This is the element-ref twin of `doorAccess`, which already deferred the
+ * content door for exactly the same reason.
+ */
+function elementAccess(a: LazyRowAttrBinding): string {
+  const slot = `__r[${a.refIndex}]`
+  return `${a.refIndex} in __r ? ${slot} : (${slot} = qsa(__e.primaryEl, '[bf="${a.slotId}"]'))`
+}
+
 /** The door constructor for this loop — see `refParts`'s "which door" note. */
 function doorCtor(lazyRow: LazyRowPlanData): string {
   return lazyRow.textNeedsRead ? 'lazyClaimSlots' : 'lazySlots'
@@ -354,6 +391,63 @@ function doorAccess(
   return `${slot} ?? (${slot} = ${doorCtor(lazyRow)}(__e.primaryEl, ${adoptedPlanVar}))`
 }
 
+/** Hoisted arm-template variable names for one conditional of one loop. */
+function condVars(mid: string, slotId: string): { trueTpl: string; falseTpl: string } {
+  const key = `${mid}_${slotId.replace(/[^A-Za-z0-9_$]/g, '_')}`
+  return { trueTpl: `__cbt_${key}`, falseTpl: `__cbf_${key}` }
+}
+
+/**
+ * A row conditional, in the same three modes as {@link emitAttrBinding}.
+ *
+ * The whole swap is `replaceWith` on the `[bf-c]` element, because
+ * `analyzeLazyConditional` has already established that the arms own nothing —
+ * no events, no children to init, no live nodes to splice. What `insert()` does
+ * per row with an effect of its own, this does with a boolean and a dedup slot.
+ *
+ * **`'create'` writes no DOM.** The row `createRow` just cloned came from the
+ * per-row template, which interpolated `cond ? trueHtml : falseHtml` itself — so
+ * the correct arm is already in place and the only thing missing is the dedup
+ * record. Swapping here would replace an element with an identical one.
+ *
+ * **`'outer'` seeds by read-compare-write (§9.3(1))** against
+ * `content.firstElementChild.outerHTML` — the browser's serialization of the arm
+ * we would install, compared with the serialization of what is there. Both sides
+ * go through the DOM, so a match means the server already rendered this arm and
+ * no write happens.
+ *
+ * The ref is REASSIGNED after a swap (`__r[i] = __n`). Without that, the next
+ * apply would hold the detached node and write into nothing.
+ */
+function emitConditional(
+  lines: string[],
+  ind: string,
+  mid: string,
+  c: LazyRowConditionalBinding,
+  mode: 'create' | 'item' | 'outer',
+): void {
+  const v = condVars(mid, c.slotId)
+  if (mode === 'create') {
+    lines.push(`${ind}__l[${c.ordinal}] = !!(${c.wrappedCondition})`)
+    return
+  }
+  const slot = `__r[${c.refIndex}]`
+  lines.push(`${ind}{ const __c = ${c.refIndex} in __r ? ${slot} : (${slot} = qsa(__e.primaryEl, '[bf-c="${c.slotId}"]'))`)
+  lines.push(`${ind}if (__c) {`)
+  lines.push(`${ind}  const __x = !!(${c.wrappedCondition})`)
+  lines.push(`${ind}  const __w = (__x ? ${v.trueTpl} : ${v.falseTpl}).content.firstElementChild`)
+  const guard = mode === 'item'
+    ? dedupGuard(c.ordinal)
+    : `__seed ? (__c.outerHTML !== __w.outerHTML) : (${dedupGuard(c.ordinal)})`
+  lines.push(`${ind}  if (${guard}) {`)
+  lines.push(`${ind}    const __n = __w.cloneNode(true)`)
+  lines.push(`${ind}    __c.replaceWith(__n)`)
+  lines.push(`${ind}    ${slot} = __n`)
+  lines.push(`${ind}  }`)
+  lines.push(`${ind}  __l[${c.ordinal}] = __x`)
+  lines.push(`${ind}} }`)
+}
+
 /** `entry.last`-backed dedup test. `in` (not a truthiness check) so a
  *  legitimately `undefined` value still records and still writes once. */
 function dedupGuard(ordinal: number): string {
@@ -366,7 +460,11 @@ function emitAttrBinding(
   a: LazyRowAttrBinding,
   mode: 'create' | 'item' | 'outer',
 ): void {
-  lines.push(`${ind}{ const __t = __r[${a.refIndex}]`)
+  // `createRow` seeded every ref from a known clone path, so there it is a
+  // plain read. An ADOPTED row starts with an EMPTY `refs` array and each
+  // binding claims its OWN slot on first use — see `elementAccess`.
+  const target = mode === 'create' ? `__r[${a.refIndex}]` : elementAccess(a)
+  lines.push(`${ind}{ const __t = ${target}`)
   lines.push(`${ind}if (__t) {`)
   lines.push(`${ind}  const __x = ${a.wrappedExpression}`)
   const guard = mode === 'create'

package/src/ir-to-client-js/control-flow/stringify/reactive-effects.ts

@@ -124,7 +124,7 @@ export function stringifyReactiveEffects(
   if (pc) {
     // Profile mode: preserve the granular per-slot/per-attr effect shape so
     // every binding keeps its own bfId (see module docstring).
-    emitAttrSlotsGranular(lines, indent, elVar, lookup, attrSlots, elementIndexBySlot, bindingBfId)
+    emitAttrSlotsGranular(lines, indent, elVar, lookup, attrSlots, elementIndexBySlot, bindingBfId, mapPreambleWrapped)
     emitOuterTexts(lines, indent, elVar, outerTexts, bindingBfId, textClaimPathExprs)
     emitPreambleRegionsEffect(lines, indent, elVar, preambleRegions, mapPreambleWrapped)
   } else {
@@ -154,6 +154,7 @@ function emitAttrSlotsGranular(
   attrSlots: readonly ReactiveAttrSlot[],
   elementIndexBySlot: ReadonlyMap<string, number> | undefined,
   bindingBfId: (slotId: string) => string,
+  mapPreambleWrapped: string | undefined,
 ): void {
   for (const slot of attrSlots) {
     const varName = `__ra_${varSlotId(slot.slotId)}`
@@ -162,6 +163,14 @@ function emitAttrSlotsGranular(
     lines.push(`${indent}if (${varName}) {`)
     for (const attr of slot.attrs) {
       lines.push(`${indent}  createEffect(() => {`)
+      // Profile mode keeps one effect per attr, so an attr reading a preamble
+      // local needs the declarations inside ITS OWN effect — there is no
+      // shared row-effect scope to hoist them into here (#2447 follow-up).
+      // Re-running per attr is the price of the per-binding bfId this mode
+      // exists to produce; `bf debug profile` is off the build hot path.
+      if (attr.readsPreamble && mapPreambleWrapped) {
+        lines.push(`${indent}    ${mapPreambleWrapped}`)
+      }
       for (const stmt of emitAttrUpdate(varName, attr.attrName, attr.wrappedExpression, attr.meta)) {
         lines.push(`${indent}    ${stmt}`)
       }
@@ -193,6 +202,11 @@ function emitPreambleRegionsEffect(
   lines.push(`${indent}})`)
 }
 
+/** Does any attr in these slots read a `.map()` preamble local (#2447)? */
+function attrsReadPreamble(attrSlots: readonly ReactiveAttrSlot[]): boolean {
+  return attrSlots.some(slot => slot.attrs.some(a => a.readsPreamble))
+}
+
 function attrLookupExpr(
   slotId: string,
   varName: string,
@@ -270,6 +284,15 @@ function emitConsolidatedRowEffect(
     return
   }
   lines.push(`${indent}createEffect(() => {`)
+  // The preamble re-run leads the body, not trails it (#2447 follow-up).
+  // It used to sit between the attr writes and the region writes, because
+  // regions were its only readers. An attribute can read a preamble local
+  // now (`class={cls}`), and it reads it from THIS scope — so the
+  // declarations have to exist before the first write, whichever kind that
+  // is. Regions are unaffected by the move: they were already downstream.
+  if (mapPreambleWrapped && (preambleRegions.length > 0 || attrsReadPreamble(attrSlots))) {
+    lines.push(`${indent}  ${mapPreambleWrapped}`)
+  }
   for (const slot of attrSlots) {
     const varName = `__ra_${varSlotId(slot.slotId)}`
     lines.push(`${indent}  if (${varName}) {`)
@@ -282,9 +305,6 @@ function emitConsolidatedRowEffect(
     }
     lines.push(`${indent}  }`)
   }
-  if (preambleRegions.length > 0 && mapPreambleWrapped) {
-    lines.push(`${indent}  ${mapPreambleWrapped}`)
-  }
   for (const text of outerTexts) {
     lines.push(`${indent}  ${writer}('${text.slotId}', String(${text.wrappedExpression}))`)
   }

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

@@ -447,7 +447,12 @@ export function buildSignalMemoEnv(
   for (const m of memos) {
     substitutions.set(m.name, {
       kind: 'call',
-      replacement: extractMemoBodyExpr(m.computation),
+      // Destructured mode (#2468): `templateComputation` (when present) has
+      // bare destructured prop refs already rewritten to `_p.X` — the
+      // spliced body lands in the module-scope template arrow, which is not
+      // a closure over init's `const value = _p.value` extraction. Mirrors
+      // the signal `templateInitialValue` handling above (#2265).
+      replacement: extractMemoBodyExpr(m.templateComputation ?? m.computation),
       freeIdentifiers: m.computationFreeIdentifiers ?? new Set(),
     })
   }

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

@@ -170,7 +170,7 @@ export function emitRegistrationAndHydration(
     // transformation runs at this layer (#1277).
     const csrInlinableConstants = csrInlinableConstantsFromCtx(ctx)
     const templateHtml = generateCsrTemplate(
-      _ir.root, csrInlinableConstants, ctx, undefined, restSpreadNames, ctx.propsObjectName, unsafeLocalNames, ctx.deferredChildSlots
+      _ir.root, csrInlinableConstants, ctx, restSpreadNames, ctx.propsObjectName, unsafeLocalNames, ctx.deferredChildSlots
     )
     if (templateHtml) {
       defParts.push(`template: (${PROPS_PARAM}) => \`${templateHtml}\``)

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

@@ -12,6 +12,7 @@ import { buildSignalMemoEnv, csrSubstitute, applyPropsRewrite, type CsrEnv } fro
 import type { ClientJsContext } from './types.ts'
 import { BF_PARENT_SCOPE_PLACEHOLDER, BF_SCOPE, escapeHtml } from '@barefootjs/shared'
 import { buildLoopChainExpr } from '../loop-chain.ts'
+import { derivesScopeFromSlot } from '../adapters/child-scope.ts'
 
 /**
  * Protect string literals from regex-based replacements.
@@ -547,12 +548,11 @@ function buildSpreadAttrsMergeCall(args: {
  *    are wrapped with `__bfSlot(EXPR, <branchSlotsVar>)` so the runtime can
  *    splice live `Node` returns into the parsed fragment instead of
  *    stringifying them via the template literal (#1213).
- *  @param insideLoop - When true, component nodes omit their `slotId` from the
- *    `renderChild` call. Each loop iteration produces its own scope (identified
- *    by `data-key`), so the parent-slot suffix would create scopes that don't
- *    match the SSR shape — see #1268 and the matching `insideLoop` guard in
- *    `generateCsrTemplate` (case `'component'`). Set to `true` when generating
- *    the per-iteration `staticItemTemplate` for static loops.
+ *  Component nodes omit their `slotId` from the `renderChild` call exactly
+ *  when `derivesScopeFromSlot()` says so — a loop-item-root component (its
+ *  own scope, identified by `data-key`) never derives from the parent slot;
+ *  a component nested below the row root does (#2444). See
+ *  `IRComponent.loopItemRoot` / `./adapters/child-scope.ts`.
  */
 /**
  * Build the per-item `<!--bf-loop-i:KEY-->` anchor comment for a whole-item
@@ -660,7 +660,7 @@ export function renderFlatMapClientBody(
     rawLeaf: true,
     renderLeaf: (ir) => {
       const key = flatMapLeafKeyExpr(ir)
-      const html = irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, 1, undefined, undefined, true)
+      const html = irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, 1, undefined, undefined)
       return `({ k: ${key ?? 'undefined'}, h: \`${html}\` })`
     },
   })
@@ -691,7 +691,7 @@ export function renderFlatMapProjectionClientBody(
   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))
+    .map((c) => irToHtmlTemplate(escapeLeafTextExpressions(c), restSpreadNames, 1, undefined, undefined))
     .join('')
   return `${chained}.map(${params} => ({ k: ${key}, h: \`${html}\` }))`
 }
@@ -728,8 +728,8 @@ function escapeLeafTextExpressions(ir: IRNode): IRNode {
   }
 }
 
-export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>, branchSlotsVar?: string, insideLoop = false, inHoistedChildren = false): string {
-  const recurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, insideLoop, inHoistedChildren)
+export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>, branchSlotsVar?: string, inHoistedChildren = false): string {
+  const recurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, inHoistedChildren)
   const wrapExpr = (expr: string) => wrapExprWithLoopParams(expr, loopParams)
   const wrapInterpolation = (expr: string): string => branchSlotsVar
     ? `__bfSlot(${expr}, ${branchSlotsVar})`
@@ -781,7 +781,7 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       }
 
       const attrs = attrParts.join(' ')
-      const childrenRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, insideLoop, false)
+      const childrenRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, false)
       const children = dangerouslyHtmlChildren(node.attrs, v => wrapExpr(v.expr)) ?? node.children.map(childrenRecurse).join('')
 
       // Non-void elements must use open+close tags (HTML parsers ignore self-closing on div, span, etc.)
@@ -853,13 +853,17 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       // instead of emitting empty placeholders (#435).
       const propsEntries = node.props
         .filter(p => p.name !== '...' && !p.name.startsWith('...') && p.name !== 'key')
-        .filter(p => !(p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()))
+        // `ref` joins the `on*` handlers here: a function prop cannot run
+        // during module-scope string rendering, and a ref closing over an
+        // init-scope setter would leak it into the template (#2468). The
+        // init path re-applies refs once real DOM exists.
+        .filter(p => p.name !== 'ref' && !(p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()))
         .map(p => {
           // `/* @client */` defers the prop to hydrate via initChild.
           if (p.clientOnly) return null
           switch (p.value.kind) {
             case 'jsx-children': {
-              const hoistedRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, insideLoop, true)
+              const hoistedRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, true)
               const childHtml = p.value.children.map(c => hoistedRecurse(c)).join('')
               return `${quotePropName(p.name)}: \`${childHtml}\``
             }
@@ -872,7 +876,15 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
             case 'expression':
             case 'template':
             case 'spread': {
-              const expr = attrValueToString(p.value) ?? 'undefined'
+              // Template-variant form (`useTemplate`): this props object
+              // lands inside the module-scope registration template, which
+              // is not a closure over init's destructured-prop extractions
+              // — the raw form leaked bare refs like `${className}` into
+              // `renderChild(...)` (#2468). Mirrors the sibling component
+              // emit sites (`irToComponentTemplateWithOpts`,
+              // `generateCsrTemplateWithOpts`), which already pick the
+              // prop-rewritten variant.
+              const expr = attrValueToString(p.value, { useTemplate: true }) ?? 'undefined'
               return `${quotePropName(p.name)}: ${expr}`
             }
           }
@@ -884,11 +896,12 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       const keyProp = node.props.find(p => p.name === 'key')
       const keyArg = keyProp ? `, ${attrValueToString(keyProp.value) ?? 'undefined'}` : ''
       // Pass slotId as suffix so $c() can find the child component by slot
-      // after branch swap. Inside a loop body each iteration owns a
-      // separate scope (identified by `data-key`), so the parent-slot
-      // suffix is dropped to avoid anchoring a deeply-nested child to a
-      // wrong component-wrapper scope (#1268).
-      const slotArg = (!insideLoop && node.slotId) ? `, '${node.slotId}'` : ''
+      // after branch swap. A loop-item-root component owns a separate scope
+      // per iteration (identified by `data-key`), so the parent-slot suffix
+      // is dropped to avoid anchoring it to a wrong component-wrapper scope
+      // (#1268) — a component nested BELOW the row root still derives from
+      // its slot, matching the Hono reference (#2444).
+      const slotArg = derivesScopeFromSlot(node) ? `, '${node.slotId}'` : ''
       return `\${renderChild('${nameForRegistryRef(node.name)}', ${propsExpr}${keyArg || (slotArg ? ', undefined' : '')}${slotArg})}`
     }
 
@@ -897,13 +910,7 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       // Increment loopDepth so inner key attrs become data-key-N
       // Forward loopParams so expressions referencing outer/inner loop params
       // get wrapped as signal accessors (e.g., task.title → task().title).
-      // `insideLoop` is preserved (not forced to `true`): downstream branch /
-      // inner-loop templates depend on the legacy slot-suffix-keeping shape
-      // to find scopes via `findSsrScopeBySlotIn`. The opt-in at the entry
-      // call site is the only place that wants the suffix dropped (#1268
-      // Case 1 — childComponent body materialize); propagating it through
-      // every nested loop regressed form-builder's inner-loop Select wiring.
-      const innerRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop)
+      const innerRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar)
       let childTemplate = node.children.map(innerRecurse).join('')
       // Whole-item conditional loops (#1665): prepend an always-present
       // `<!--bf-loop-i:KEY-->` anchor before each item's (possibly empty)
@@ -938,13 +945,13 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
         // 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(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop),
+          renderLeaf: (ir) => irToHtmlTemplate(stripLeafKeyAttr(ir), restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar),
         })
         mapExpr = `\${${wrappedArray}.flatMap(${node.flatMapCallback.params} => ${body}).join('')}`
       } else if (node.preamble) {
         // Stage 3 / D4 — render JSX leaves in an arbitrary array-builder
         // preamble (the hydrate-template context uses the bare loop param).
-        const preamble = renderPreamble(node.preamble, { textVariant: 'client', renderLeaf: (ir) => irToHtmlTemplate(ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop) })
+        const preamble = renderPreamble(node.preamble, { textVariant: 'client', renderLeaf: (ir) => irToHtmlTemplate(ir, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar) })
         mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => { ${preamble} return \`${childTemplate}\` }).join('')}`
       } else {
         mapExpr = `\${${wrappedArray}.${iterMethod}(${callbackParam} => \`${childTemplate}\`).join('')}`
@@ -1563,7 +1570,6 @@ export interface TemplateOptions {
    * `compute-inlinability` (#1277).
    */
   csrEnv?: CsrEnv
-  insideLoop?: boolean
   loopDepth?: number
   /**
    * Names bound by the ENCLOSING loops' callback params (item / index /
@@ -1799,7 +1805,11 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
       // Use renderChild() to render child component's template at runtime (#435)
       const propsEntries = node.props
         .filter(p => p.name !== '...' && !p.name.startsWith('...') && p.name !== 'key')
-        .filter(p => !(p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()))
+        // `ref` joins the `on*` handlers here: a function prop cannot run
+        // during module-scope string rendering, and a ref closing over an
+        // init-scope setter would leak it into the template (#2468). The
+        // init path re-applies refs once real DOM exists.
+        .filter(p => p.name !== 'ref' && !(p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()))
         .map(p => {
           // `/* @client */` defers the prop to hydrate via initChild.
           if (p.clientOnly) return null
@@ -1990,7 +2000,6 @@ export function generateCsrTemplate(
   node: IRNode,
   inlinableConstants: Map<string, string> | undefined,
   ctx: ClientJsContext,
-  insideLoop?: boolean,
   restSpreadNames?: Set<string>,
   propsObjectName?: string | null,
   unsafeLocalNames?: Set<string>,
@@ -2010,7 +2019,7 @@ export function generateCsrTemplate(
     }
   }
   const effectiveUnsafeLocalNames = mergeCsrNullUnsafe(ctx, unsafeLocalNames)
-  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, insideLoop, unsafeLocalNames: effectiveUnsafeLocalNames, deferredChildSlots, loopDepth: -1 })
+  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, unsafeLocalNames: effectiveUnsafeLocalNames, deferredChildSlots, loopDepth: -1 })
 }
 
 /**
@@ -2171,6 +2180,7 @@ export function computeDeferredChildSlots(
             // filter set MUST mirror the `propsEntries` filter in the CSR
             // `component` emit below so the deferral decision matches output.
             if (p.name === '...' || p.name.startsWith('...') || p.name === 'key') return false
+            if (p.name === 'ref') return false
             if (p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()) return false
             if (p.clientOnly) return false
             return propResolvesUnsafe(p, env, unsafeLocalNames)
@@ -2204,7 +2214,7 @@ export function computeDeferredChildSlots(
 }
 
 function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): string {
-  const { restSpreadNames, propsObjectName, csrEnv, insideLoop, unsafeLocalNames, loopDepth = 0 } = opts
+  const { restSpreadNames, propsObjectName, csrEnv, unsafeLocalNames, loopDepth = 0 } = opts
   const env: CsrEnv = csrEnv ?? { substitutions: new Map(), propsObjectName: propsObjectName ?? null }
   const transformExpr = (expr: string, templateExpr?: string): string => {
     // Single AST substitution pass: replaces signal getter calls
@@ -2241,12 +2251,10 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
   }
 
   // `recurse` preserves `inHoistedChildren` for structural pass-through
-  // (fragment / conditional); `childrenRecurse` and `recurseInLoop`
-  // clear it — a new element root or loop iteration starts a fresh
-  // scope. (#1320)
+  // (fragment / conditional); `childrenRecurse` clears it — a new element
+  // root starts a fresh scope. (#1320)
   const recurse = (n: IRNode): string => generateCsrTemplateWithOpts(n, opts)
   const childrenRecurse = (n: IRNode): string => generateCsrTemplateWithOpts(n, { ...opts, inHoistedChildren: false })
-  const recurseInLoop = (n: IRNode): string => generateCsrTemplateWithOpts(n, { ...opts, insideLoop: true, loopDepth: loopDepth + 1, inHoistedChildren: false })
 
   switch (node.type) {
     case 'element': {
@@ -2399,7 +2407,11 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
 
       const propsEntries = node.props
         .filter(p => p.name !== '...' && !p.name.startsWith('...') && p.name !== 'key')
-        .filter(p => !(p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()))
+        // `ref` joins the `on*` handlers here: a function prop cannot run
+        // during module-scope string rendering, and a ref closing over an
+        // init-scope setter would leak it into the template (#2468). The
+        // init path re-applies refs once real DOM exists.
+        .filter(p => p.name !== 'ref' && !(p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()))
         .map(p => {
           // `/* @client */` defers the prop to hydrate. Drop from the
           // SSR `renderChild` props — `initChild`'s `propsExpr` getter
@@ -2441,7 +2453,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
       const propsExpr = propsEntries.length > 0 ? `{${propsEntries.join(', ')}}` : '{}'
       const keyProp = node.props.find(p => p.name === 'key')
       const keyArg = keyProp ? `, ${transformKeyValue(keyProp.value, transformExpr)}` : ''
-      const slotArg = (!insideLoop && node.slotId) ? `, '${node.slotId}'` : ''
+      const slotArg = derivesScopeFromSlot(node) ? `, '${node.slotId}'` : ''
       return `\${renderChild('${nameForRegistryRef(node.name)}', ${propsExpr}${keyArg || (slotArg ? ', undefined' : '')}${slotArg})}`
     }
 
@@ -2469,7 +2481,6 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
       }
       const recurseInLoopBody = (n: IRNode): string => generateCsrTemplateWithOpts(n, {
         ...opts,
-        insideLoop: true,
         loopDepth: loopDepth + 1,
         inHoistedChildren: false,
         loopBoundNames: boundHere,

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

@@ -267,7 +267,7 @@ function generateTemplateOnlyMount(ir: ComponentIR, ctx: ClientJsContext): strin
   if (!templateHtml) {
     const csrInlinableConstants = csrInlinableConstantsFromCtx(ctx)
     templateHtml = generateCsrTemplate(
-      ir.root, csrInlinableConstants, ctx, undefined, restSpreadNames, ctx.propsObjectName, unsafeLocalNames
+      ir.root, csrInlinableConstants, ctx, restSpreadNames, ctx.propsObjectName, unsafeLocalNames
     )
   }
 

package/src/ir-to-client-js/plan/build-declaration-emit.ts

@@ -95,6 +95,7 @@ function buildSignalPlan(
         kind: 'signal',
         getter: signal.getter,
         setter: signal.setter,
+        getterElided: signal.getterElided,
         initialValueExpr: '',
         controlledEffect: null,
         initializerOverride: `${factory}()`,
@@ -109,6 +110,7 @@ function buildSignalPlan(
     kind: 'signal',
     getter: signal.getter,
     setter: signal.setter,
+    getterElided: signal.getterElided,
     initialValueExpr: resolveSignalInitialValue(signal, ctx, lookups),
     controlledEffect,
     branchCondition: signal.branchCondition,