@barefootjs/jsx 0.26.4 → 0.28.0

package/src/ir-to-client-js/client-only-elision.ts

@@ -0,0 +1,273 @@
+/**
+ * Slot unification Step B (`spec/slot-unification.md` §3(b), §5 "Step B —
+ * marker elision"): decide, EXACTLY ONCE and BEFORE either `adapter.generate`
+ * (SSR) or `generateClientJs` (CSR) run, which `/* @client *\/` text slots
+ * can drop their `<!--bf:sN-->…<!--/-->` marker pair entirely from both
+ * outputs. Every consumer (all nine SSR adapters' `renderExpression`, and
+ * the CSR emitters in `html-template.ts`) reads the single
+ * `IRExpression.markerless` flag this pass writes — nobody re-derives the
+ * decision, per CLAUDE.md's "Never add compiler options/hooks for
+ * tool-specific output rewriting" spirit: one door in, everyone reads it.
+ *
+ * Scope — deliberately the NARROWEST slice of §3(b)'s elision rule that is
+ * fully sound today, not the general case:
+ *
+ *   Only `expr.clientOnly && expr.slotId` expressions OUTSIDE any loop or
+ *   conditional branch (i.e. reachable from the component's own render tree
+ *   by walking only `element`/`text`/`expression`/`fragment` nodes).
+ *
+ * Why THIS slice and not ordinary reactive text slots (loop rows,
+ * conditional branches): every other kind of slot's SSR-rendered width is
+ * DATA-DEPENDENT — an ordinary `{item.name}` may render empty or non-empty
+ * per request, so a LATER sibling's absolute child-index path would only be
+ * valid for the specific width THIS request happened to produce, not for
+ * every request the compiled function ever serves. `/* @client *\/`
+ * expressions are the one case free of that problem: SSR can never evaluate
+ * client-only JS (the whole point of the escape valve), so its rendered
+ * width is deterministically ZERO on every request, for every adapter, with
+ * no data dependence at all. That determinism is what makes computing a
+ * real, reusable, hydration-safe path sound here without also solving the
+ * general "does an earlier sibling's width vary by request" problem.
+ *
+ * Path safety within that scope — the part that generalizes A3's
+ * `computeSkeletonSlotPaths` (`html-template.ts`) rather than reinventing
+ * it: paths are root-relative child-index chains, exactly like that
+ * function's, walked in document order with the SAME "once we hit something
+ * whose contributed width isn't a compile-time constant, every remaining
+ * sibling AND everything nested inside it loses eligibility" rule (nested
+ * content reached only through an uncertain-index sibling would resolve an
+ * absolute path through that uncertain index — silently wrong, not loud, so
+ * it must never be attempted). Concretely, walking a children list left to
+ * right:
+ *   - a static `element` always contributes exactly one node — recurse into
+ *     its own children as an independent, freshly-indexed scope (its own
+ *     internal accounting can't leak out, and nothing external can poison
+ *     it either, since the element itself is a fixed anchor regardless of
+ *     what's inside it);
+ *   - static `text` contributes a node per HTML-parser text-run-merging
+ *     rules (adjacent text/expression children collapse into ONE Text
+ *     node — mirrors `computeSkeletonSlotPaths`'s `pendingText` tracking);
+ *   - a `clientOnly` expression with a slotId is the one ELIGIBLE case,
+ *     PROVIDED it is not itself part of a merged text run (rule (i) — the
+ *     `/* @client *\/` slot must not be immediately adjacent, once markers
+ *     are gone, to loose text or another expression, or the HTML parser
+ *     would merge them into one Text node with no way to tell which
+ *     content is which). Once one is elided, this level (and everything
+ *     nested inside any later sibling) is marked ineligible for the
+ *     remainder of the walk at this level — see the "freeze" note below;
+ *   - any other `expression` (a real reactive/static text or markup slot),
+ *     any `conditional`/`loop`/`component`/`async`/`provider`/
+ *     `if-statement`/`slot` node, is data-dependent or opaque width and
+ *     FREEZES the rest of this children list (see below) — this is
+ *     strictly conservative: it also means a `/* @client *\/` expression
+ *     is never eligible once any of these appears earlier at the same
+ *     level, even though `/* @client *\/`'s own width is always zero,
+ *     because SIBLINGS reached only via nested recursion past that point
+ *     would otherwise resolve an absolute path through the frozen node's
+ *     uncertain contributed width;
+ *   - the same hazard-tag / force-close-group / void-element / `<tr>`
+ *     foster-parenting guards `computeSkeletonSlotPaths` uses (imported,
+ *     not re-derived) abort the ENTIRE walk (a global bail, exactly like
+ *     that function's `state.bailed`) — a parser hazard means every index
+ *     computed anywhere in this tree is suspect, not just the ones near
+ *     the hazard, so "don't guess" means don't guess about the blast
+ *     radius either.
+ *
+ * "Freeze" (the one simplification versus a maximally-precise per-branch
+ * eligibility tracker): once ANY `/* @client *\/` slot at a given level is
+ * elided — OR once anything data-dependent/opaque is seen at that level —
+ * that level's remaining siblings (and anything nested only through them)
+ * stop being assigned real paths for the rest of THIS walk, even though a
+ * maximally precise analysis could sometimes still find one. This caps
+ * elision at (at most) one `/* @client *\/` slot per static subtree —
+ * conservative by design, matching the elision rule's own framing, and it
+ * guarantees two elided slots can never end up needing an insertion whose
+ * reference node depends on the other's still-unresolved width. Freezing is
+ * PER CHILDREN-LIST (an element's own children start a fresh, unfrozen
+ * scope) — global-bail is reserved for hazard tags alone.
+ *
+ * Deferred (loudly, not silently): ordinary reactive text slots in loop
+ * rows / conditional branches keep their markers — see above for why
+ * widening this to data-dependent-width content needs a materially
+ * different (and per-adapter-verified) safety argument that this PR does
+ * not attempt.
+ */
+
+import type { IRNode, IRExpression } from '../types.ts'
+import {
+  VOID_ELEMENTS,
+  SKELETON_PATH_HAZARD_TAGS,
+  skeletonForceCloseGroup,
+  hasForeignTableRowContent,
+  flattenSkeletonChildren,
+} from './html-template.ts'
+
+/** Global bail, mirroring `computeSkeletonSlotPaths`'s `state.bailed`: once
+ *  a parser hazard is seen anywhere, every remaining step of this ONE
+ *  `decideClientOnlyElision` call becomes a no-op. Slots already elided
+ *  before the hazard was reached keep their `markerless`/`elidedPath` —
+ *  those paths were computed from safe ground and remain valid; only
+ *  FURTHER assignment stops. */
+interface ElisionState {
+  bailed: boolean
+}
+
+/**
+ * Entry point: mutates `root`'s `expression` nodes in place, setting
+ * `markerless`/`elidedPath` on every eligible `/* @client *\/` slot found.
+ * Safe to call on any component's render tree; a tree with none simply
+ * mutates nothing.
+ */
+export function decideClientOnlyElision(root: IRNode): void {
+  walkNode(root, [], new Set(), { bailed: false })
+}
+
+/** Walk one node that occupies a known position (`path`) in its parent's
+ *  children. Only `element`/`fragment` are ever recursed into by the
+ *  children-list walker below — this wrapper exists so both the top-level
+ *  call and `walkChildren`'s per-element recursion can share one path. */
+function walkNode(
+  node: IRNode,
+  path: readonly number[],
+  forceCloseAncestors: ReadonlySet<number>,
+  state: ElisionState,
+): void {
+  if (state.bailed) return
+  if (node.type === 'element') {
+    if (!elementIsPathSafe(node.tag, flattenSkeletonChildren(node.children))) {
+      state.bailed = true
+      return
+    }
+    const groupIdx = skeletonForceCloseGroup(node.tag)
+    if (groupIdx >= 0 && forceCloseAncestors.has(groupIdx)) {
+      state.bailed = true
+      return
+    }
+    const nextAncestors = groupIdx >= 0 ? new Set([...forceCloseAncestors, groupIdx]) : forceCloseAncestors
+    walkChildren(flattenSkeletonChildren(node.children), path, nextAncestors, state)
+  } else if (node.type === 'fragment') {
+    walkChildren(flattenSkeletonChildren(node.children), path, forceCloseAncestors, state)
+  }
+  // Any other root shape (a bare conditional/loop/component return, etc.)
+  // has no static children list to walk — nothing to do.
+}
+
+/**
+ * Walk one parent's (already-fragment-flattened) children left to right,
+ * assigning paths to eligible `/* @client *\/` slots. `parentPath` is the
+ * path to the PARENT of this children list (the element/root whose
+ * `childNodes` these indices are relative to). `forceCloseAncestors`
+ * mirrors `computeSkeletonSlotPaths`'s ancestor-threaded force-close-group
+ * tracking (`<h2>` inside an open `<h1>`, `<li>` inside an open `<li>`, …) —
+ * threaded down through element recursion, exactly like that function.
+ * `frozen` is local to THIS call (this one children list) — an element's
+ * own children get a fresh, unfrozen scope regardless of what froze here.
+ */
+function walkChildren(
+  children: readonly IRNode[],
+  parentPath: readonly number[],
+  forceCloseAncestors: ReadonlySet<number>,
+  state: ElisionState,
+): void {
+  let frozen = false
+  let idx = 0
+  let pendingText = false
+
+  for (let i = 0; i < children.length; i++) {
+    if (state.bailed) return
+    const child = children[i]
+
+    switch (child.type) {
+      case 'text': {
+        if (child.value === '') continue
+        if (!pendingText) idx += 1
+        pendingText = true
+        continue
+      }
+
+      case 'expression': {
+        if (child.expr === 'null' || child.expr === 'undefined') continue
+        if (child.clientOnly && child.slotId) {
+          const adjacent = isTextLike(children[i - 1]) || isTextLike(children[i + 1])
+          if (!frozen && !adjacent) {
+            markElided(child, [...parentPath, idx])
+            frozen = true // one elision per level — see module docstring
+          } else {
+            frozen = true // still freeze: an un-elided expression here is
+            // no different from any other data-dependent-width sibling.
+          }
+          idx += 1
+          pendingText = false
+          continue
+        }
+        // Any other expression — data-dependent width. Freeze the rest of
+        // this level; still consume ONE index (best-effort bookkeeping —
+        // nothing downstream reads `idx` past this point since `frozen`
+        // blocks any further assignment).
+        frozen = true
+        idx += 1
+        pendingText = false
+        continue
+      }
+
+      case 'element': {
+        if (!elementIsPathSafe(child.tag, flattenSkeletonChildren(child.children))) {
+          // Hazard shape: bail the WHOLE walk (matches
+          // `computeSkeletonSlotPaths`'s "don't guess" stance), not just
+          // this level — a parser hazard means indices anywhere in this
+          // tree are untrustworthy, not only the ones near it.
+          state.bailed = true
+          return
+        }
+        if (!frozen) {
+          walkNode(child, [...parentPath, idx], forceCloseAncestors, state)
+        }
+        idx += 1
+        pendingText = false
+        continue
+      }
+
+      case 'fragment':
+        continue // already flattened
+
+      default:
+        // conditional / loop / component / async / provider / if-statement /
+        // slot: opaque or variable width. Freeze the rest of this level.
+        frozen = true
+        idx += 1
+        pendingText = false
+        continue
+    }
+  }
+}
+
+/** True for a node that would merge (per HTML text-node-merging rules) with
+ *  an adjacent bare-text-position slot if that slot's markers were removed —
+ *  rule (i) of §3(b). `undefined` (no sibling — start/end of the children
+ *  list) is never adjacent. */
+function isTextLike(node: IRNode | undefined): boolean {
+  if (!node) return false
+  if (node.type === 'text') return node.value !== ''
+  if (node.type === 'expression') return node.expr !== 'null' && node.expr !== 'undefined'
+  return false
+}
+
+function markElided(expr: IRExpression, path: readonly number[]): void {
+  expr.markerless = true
+  expr.elidedPath = path
+}
+
+/**
+ * Mirrors `computeSkeletonSlotPaths`'s per-element safety checks (hazard
+ * tags, void elements, `<tr>` foster-parenting) without re-deriving the
+ * underlying tag sets — imported from `html-template.ts` so the two walks
+ * can never silently diverge on which shapes are hazardous. Force-close
+ * groups are checked separately by the caller (`walkNode`), which has the
+ * ancestor set this check does not.
+ */
+function elementIsPathSafe(tag: string, flatChildren: readonly IRNode[]): boolean {
+  if (SKELETON_PATH_HAZARD_TAGS.has(tag)) return false
+  if (VOID_ELEMENTS.has(tag) && flatChildren.length > 0) return false
+  if (tag === 'tr' && hasForeignTableRowContent(flatChildren)) return false
+  return true
+}

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

@@ -414,8 +414,8 @@ export function collectInnerLoops(
 
 /**
  * Decide whether a loop's runtime rendering needs element reconciliation
- * (reconcileElements + composite item rendering) rather than the simple
- * template-per-item path, and collect inner-loop metadata for its body.
+ * (mapArray/mapArrayAnchored + composite item rendering) rather than the
+ * simple template-per-item path, and collect inner-loop metadata for its body.
  *
  * Used by both the top-level `case 'loop'` in `collectElements` and the
  * branch-loop collector in `collectBranchLoops`. Each call site applies
@@ -595,7 +595,11 @@ export function collectElements(
     },
     expression: ({ node: ex, scope: inCond }) => {
       if (ex.clientOnly && ex.slotId) {
-        ctx.clientOnlyElements.push({ slotId: ex.slotId, expression: ex.expr })
+        ctx.clientOnlyElements.push({
+          slotId: ex.slotId,
+          expression: ex.expr,
+          elidedPath: ex.markerless ? ex.elidedPath : undefined,
+        })
         return
       }
       if (!ex.slotId || inCond) return
@@ -1113,7 +1117,7 @@ function collectBranchLoops(
         : decideLoopRendering(n, siblingOffsets, undefined)
 
       // Build the item template from loop children.
-      // Use loopDepth=0: this loop gets its own reconcileElements (independent
+      // Use loopDepth=0: this loop gets its own mapArray/mapArrayAnchored call (independent
       // from the conditional's template), so items use data-key (not data-key-1).
       // Pass loopParams so expressions reference the per-item signal accessor,
       // keeping the template consistent with reactive effect expressions that
@@ -1409,19 +1413,54 @@ function summarizeLoopChildBranch(
     // on the branch root yields exactly this branch's direct bindings
     // without re-collecting what a nested arm already owns (#2347).
     reactiveAttrs: collectLoopChildReactiveAttrs(node, ctx, loopParam, loopParamBindings, true),
-    // Skip when the branch's ENTIRE content is a single bare `expression`
-    // (no wrapping element) — e.g. a hoisted `renderNode={(n) => <Pill/>}`
-    // callback (#1211/#1213). That value is already fully re-evaluated and
-    // spliced via `__bfSlot` whenever `insert()` (re-)mounts this branch;
-    // an *additional* nested createEffect for the same expression re-calls
-    // it and creates a second, independent live element (a JSX-callback
-    // result isn't idempotent to re-invoke the way a plain signal read is),
-    // and the loop-child arm's `$t()`-based anchor lookup — designed for
-    // text nodes — doesn't cleanly displace an already-mounted Element,
-    // so the second instance lands beside the first instead of replacing
-    // it. A text *nested inside* a static wrapper element in the branch
-    // (the element-descent case) is unaffected and still collected below.
-    reactiveTexts: node.type === 'expression'
+    // Skip ONLY when the branch's entire content is a single bare
+    // `expression` (no wrapping element) that MAY yield a live DOM node —
+    // i.e. it contains a call anywhere (`node.hasFunctionCalls`, computed
+    // by the AST walk in `exprHasFunctionCalls`/jsx-to-ir.ts, recursively —
+    // catches a call nested in a template literal or a nested ternary, not
+    // just a top-level call). A call can return an Element (a hoisted
+    // `renderNode={(n) => <Pill/>}` callback lowered to a component call,
+    // #1211/#1213) and the compiler cannot tell from syntax whether it does
+    // — both `renderChild(...)` and `_p.renderCell(...)` are a
+    // `CallExpression` — so this stays conservative for ANY call, not just
+    // ones known to return JSX. Re-evaluating a non-idempotent call inside
+    // an *additional* nested createEffect (on top of the eval already done
+    // for the `__bfSlot`-wrapped splice whenever `insert()` (re-)mounts this
+    // branch) would call it again on every unrelated tick and discard the
+    // previous element's listeners/state.
+    //
+    // Everything else — a property access (`row.label`), an identifier, a
+    // literal, a template literal, string concatenation, or a nested
+    // ternary of those — cannot itself construct a DOM node (only a JSX
+    // literal or a call can, and a JSX literal branch is never `type:
+    // 'expression'` in the first place — see `transformJsxExpression`), so
+    // it is safe to collect. This is the fix for the loop-branch-stale-text
+    // defect: a keyed loop row whose branch is e.g. `row.done ? row.label :
+    // 'pending'` previously had NO update path at all when `row.label`
+    // changed without `row.done` flipping — `insert()` (runtime/insert.ts)
+    // correctly no-ops when its condition is unchanged (branch-internal
+    // updates are deliberately the effect system's job, not DOM
+    // replacement's), but with reactiveTexts always `[]` for this shape,
+    // no effect existed either, so the branch was frozen at its mount-time
+    // value. The stale rationale in a prior version of this comment blamed
+    // "the loop-child arm's `$t()`-based anchor lookup", but `$t()` no
+    // longer exists — it was one of four content mechanisms deleted by the
+    // slot-unification work. The current claim door
+    // (`stringifyLoopChildArm` → `lazySlots(..., kind: 'markup')` →
+    // `writeMarkup`, runtime/claim-slots.ts) clears the claimed range and
+    // splices the Node by identity, so "lands beside the first" cannot
+    // happen through it; only the call's non-idempotence still applies, and
+    // that alone is why the skip narrows rather than disappears.
+    //
+    // Collecting here is necessary but not sufficient: `n.slotId` must also
+    // be set for `collectLoopChildReactiveTexts` (ir-to-client-js/
+    // reactivity.ts) to do anything — see `transformConditionalBranch`'s
+    // `refsLoopParam` check (jsx-to-ir.ts) for the matching half of this fix
+    // that gives a bare loop-item-reading branch a slotId at all, which also
+    // makes `irToHtmlTemplate` emit its `<!--bf:sN-->…<!--/-->` marker (the
+    // same call builds both the SSR and the CSR/hydration template, so the
+    // two can't disagree on shape).
+    reactiveTexts: node.type === 'expression' && node.hasFunctionCalls
       ? []
       : collectLoopChildReactiveTexts(node, ctx, loopParam, loopParamBindings, true),
   }

package/src/ir-to-client-js/control-flow/plan/branch-loop.ts

@@ -18,6 +18,7 @@
 import type { CompositeLoopPlan, LoopChildRefBinding, PreambleRegionPlan } from './loop.ts'
 import type { EventDelegationPlan } from './event-delegation.ts'
 import type { ReactiveEffectsPlan } from './reactive-effects.ts'
+import type { LazyRowPlanData } from './build-lazy-row.ts'
 
 export interface BranchPlainLoopPlan {
   /**
@@ -89,6 +90,11 @@ export interface BranchPlainLoopPlan {
    * renderItem layout, mirroring the top-level plain plan.
    */
   preambleRegions: readonly PreambleRegionPlan[]
+  /**
+   * Lazy row graph plan (`spec/slot-unification.md` §9, L3) — see
+   * `PlainLoopVariant.lazyRow`. Undefined ⇒ today's eager emission.
+   */
+  lazyRow?: LazyRowPlanData
 }
 
 export interface BranchCompositeLoopPlan {

package/src/ir-to-client-js/control-flow/plan/build-branch-loop.ts

@@ -15,6 +15,8 @@ import { buildChainedArrayExpr, varSlotId, wrapLoopParamAsAccessor } from '../..
 import { buildBranchCompositePlan } from './build-composite-loop.ts'
 import { buildBranchLoopDelegationPlan } from './build-event-delegation.ts'
 import { buildReactiveEffectsPlan } from './build-reactive-effects.ts'
+import { buildLazyRowPlan } from './build-lazy-row.ts'
+import type { LazyRowScopeInfo } from './lazy-row-eligibility.ts'
 import { destructureLoopParam, loopKeyFn, buildChildRefBindings, buildPreambleRegionPlans } from '../shared.ts'
 import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
@@ -23,7 +25,11 @@ import type {
   BranchPlainLoopPlan,
 } from './branch-loop.ts'
 
-export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: string): BranchLoopPlan {
+export function buildBranchLoopPlan(
+  loop: BranchLoop,
+  profileComponentName?: string,
+  lazyScope?: LazyRowScopeInfo,
+): BranchLoopPlan {
   const containerSlotId = loop.containerSlotId
   const cv = varSlotId(containerSlotId)
   const containerVar = `__loop_${cv}`
@@ -45,6 +51,17 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
 
   // flatMap descriptor mode — see buildPlainLoopPlan (build-loop.ts).
   const fm = loop.flatMapClient
+  const arrayExpr = fm
+    ? `(${buildChainedArrayExpr(loop)}).flatMap(${fm.params} => ${fm.body})`
+    : buildChainedArrayExpr(loop)
+  const indexParam = loop.index || '__idx'
+  const mapPreambleWrapped = loop.preamble
+    ? renderPreamble(loop.preamble, {
+        transformJs: (t) => wrapLoopParamAsAccessor(t, loop.param, loop.paramBindings),
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
+      })
+    : ''
+  const preambleRegions = buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings)
   const plan: BranchPlainLoopPlan = {
     kind: 'plain',
     rowConstruction: 'string-template',
@@ -52,23 +69,29 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
     containerVar,
     markerId: loop.markerId,
     flatMapLeafItem: fm ? true : undefined,
-    arrayExpr: fm
-      ? `(${buildChainedArrayExpr(loop)}).flatMap(${fm.params} => ${fm.body})`
-      : buildChainedArrayExpr(loop),
+    arrayExpr,
     keyFn: fm
       ? (fm.keyed ? '(__bfD, __bfI) => String(__bfD.k ?? __bfI)' : 'null')
       : loopKeyFn(loop),
     paramHead,
     paramUnwrap,
-    indexParam: loop.index || '__idx',
+    indexParam,
     // Wrap loop-param references to signal-accessor form so the preamble
     // matches the template literal's already-wrapped reads (#1065).
-    mapPreambleWrapped: loop.preamble
-      ? renderPreamble(loop.preamble, {
-          transformJs: (t) => wrapLoopParamAsAccessor(t, loop.param, loop.paramBindings),
-          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
-        })
-      : '',
+    mapPreambleWrapped,
+    // Lazy row graph (§9, L3) — undefined for every ineligible loop.
+    lazyRow: buildLazyRowPlan({
+      loop,
+      arrayExpr,
+      indexParam,
+      paramUnwrap,
+      mapPreambleWrapped,
+      preambleRegionCount: preambleRegions.length,
+      callSite: 'branch-plain',
+      flatMapLeafItem: Boolean(fm),
+      anchored: false,
+      scope: lazyScope,
+    }) ?? undefined,
     template: loop.template,
     reactiveEffects: hasReactiveEffects
       ? buildReactiveEffectsPlan({
@@ -82,7 +105,7 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
       : null,
     eventDelegation: buildBranchLoopDelegationPlan(loop, cv, profileComponentName),
     childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings),
-    preambleRegions: buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings),
+    preambleRegions,
     bodyIsMultiRoot: loop.bodyIsMultiRoot ?? false,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${containerSlotId}` : undefined,
   }

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

@@ -14,6 +14,7 @@ import type {
 } from '../../types.ts'
 import { addCondAttrToTemplate } from '../../html-template.ts'
 import { buildBranchLoopPlan } from './build-branch-loop.ts'
+import type { LazyRowScopeInfo } from './lazy-row-eligibility.ts'
 import type {
   InsertPlan,
   InsertArm,
@@ -26,6 +27,12 @@ export interface BuildInsertOptions {
   eventNameMode: 'dom' | 'raw'
   /** Owning component name in profile mode (#1690, SR3) — else undefined. */
   profileComponentName?: string
+  /**
+   * Component-scope name facts for the lazy row graph gate
+   * (`spec/slot-unification.md` §9.4). Threaded down to branch-scoped plain
+   * loops; omitted → those loops keep today's eager emission.
+   */
+  lazyScope?: LazyRowScopeInfo
 }
 
 export function buildInsertPlan(
@@ -88,13 +95,13 @@ function buildArmBody(branch: BranchSummary, options: BuildInsertOptions): ArmBo
       expression: t.expression,
     })),
     // Branch-scoped loops, fully Plan-built (Item 2 final migration).
-    loops: branch.loops.map(l => buildBranchLoopPlan(l, pc)),
+    loops: branch.loops.map(l => buildBranchLoopPlan(l, pc, options.lazyScope)),
     // Nested conditionals are themselves InsertPlans — built recursively so
     // the same stringifier handles arbitrary depth. Their scope is always
     // `__branchScope` (the parent arm's bindEvents argument), regardless of
     // the outer scope; only the eventNameMode is inherited.
     conditionals: branch.conditionals.map(c =>
-      buildInsertPlan(c, { scope: { kind: 'branchScope' }, eventNameMode: options.eventNameMode, profileComponentName: pc }),
+      buildInsertPlan(c, { scope: { kind: 'branchScope' }, eventNameMode: options.eventNameMode, profileComponentName: pc, lazyScope: options.lazyScope }),
     ),
   }
 }