@barefootjs/cli 0.27.0 → 0.28.0

package/dist/index.js

@@ -11161,7 +11161,8 @@ function transformConditionalBranch(node, ctx2) {
   const callsReactive = exprCallsReactiveGetters(node, ctx2);
   const hasCalls = exprHasFunctionCalls(node);
   const reactive = isReactiveExpression(exprText, ctx2, node) || isReactiveOrigin(branchOrigin);
-  const needsSlot = reactive || callsReactive;
+  const refsLoopParam = branchOrigin.freeRefs?.some((r2) => r2.kind === "render-item") ?? false;
+  const needsSlot = reactive || callsReactive || refsLoopParam;
   const slotId = needsSlot ? generateSlotId(ctx2) : null;
   return {
     type: "expression",
@@ -14761,19 +14762,54 @@ function summarizeLoopChildBranch(node, ctx2, siblingOffsets, loopParam, loopPar
     // on the branch root yields exactly this branch's direct bindings
     // without re-collecting what a nested arm already owns (#2347).
     reactiveAttrs: collectLoopChildReactiveAttrs(node, ctx2, 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" ? [] : collectLoopChildReactiveTexts(node, ctx2, loopParam, loopParamBindings, true)
+    // 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, ctx2, loopParam, loopParamBindings, true)
   };
 }
 var EMPTY_RENDER_EXPRS, branchInnerLoopOptions;
@@ -15339,6 +15375,7 @@ var init_imports = __esm({
       "getLoopNodes",
       "mapArray",
       "mapArrayAnchored",
+      "mapArrayLazy",
       "patchLeaf",
       "createDisposableEffect",
       "createComponent",
@@ -15370,8 +15407,16 @@ var init_imports = __esm({
       // 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.
+      // `lazyClaimSlots` is the read-capable twin of `lazySlots` over the same
+      // claim — emitted only by lazy loops that seed an outer-involving TEXT
+      // binding by read-compare-write (§9.3(1)).
+      // `textOrNode` is the 'text' door's Node guard: a child-position value that
+      // turns out to be a live Node must reach the writer as a Node so the claim
+      // can promote to 'markup', never as `String(node)`.
       "claimSlots",
       "lazySlots",
+      "lazyClaimSlots",
+      "textOrNode",
       // Profile mode (#1690, SR3) — turn-boundary markers around event handlers.
       "beginTurn",
       "endTurn",
@@ -18494,8 +18539,340 @@ var init_build_event_delegation = __esm({
   }
 });
 
+// ../jsx/src/ir-to-client-js/control-flow/plan/lazy-row-eligibility.ts
+function lazyRowEligibility(args2) {
+  const { shape, bindings, arraySourceIdentifiers, scope } = args2;
+  if (scope.profile) return NO("profile mode keeps the granular eager emission");
+  if (shape.callSite !== "plain" && shape.callSite !== "branch-plain") {
+    return NO(`call site '${shape.callSite}' is not a plain loop row`);
+  }
+  if (shape.flatMapLeafItem) return NO("flatMap descriptor loop (build-or-patch renderItem)");
+  if (shape.anchored) return NO("anchored whole-item-conditional loop");
+  if (shape.bodyIsMultiRoot) return NO("multi-root (Fragment) row");
+  if (!shape.hasExplicitKey) return NO("index-keyed loop (no explicit key)");
+  if (shape.conditionalCount > 0) return NO("row contains a reactive conditional");
+  if (shape.childRefCount > 0) return NO("row has imperative child refs");
+  if (shape.hasChildComponent) return NO("row body is a child component");
+  if (shape.nestedComponentCount > 0) return NO("row contains nested child components");
+  if (shape.innerLoopCount > 0) return NO("row contains an inner loop");
+  if (shape.hasMapPreamble) return NO("row has a map-callback preamble (may declare row-local reactivity)");
+  if (shape.preambleRegionCount > 0) return NO("row has preamble-patched regions");
+  if (shape.hasParamUnwrap) return NO("destructured loop param without param bindings");
+  for (const b of bindings) {
+    if (b.referencesIndex) {
+      return NO(`binding on slot ${b.slotId} references the loop index parameter`);
+    }
+    if (b.opaqueOuterNames.includes(UNKNOWN_IDENTIFIERS)) {
+      return NO(`binding on slot ${b.slotId} has no analyzable identifier set`);
+    }
+  }
+  if (!arraySourceIdentifiers) return NO("loop source free identifiers unavailable");
+  const sourceGate = checkSourceConsistency(arraySourceIdentifiers, scope);
+  if (sourceGate) return NO(`loop source is not provably hydration-consistent: ${sourceGate}`);
+  return { eligible: true };
+}
+function checkSourceConsistency(names, scope) {
+  const seen = /* @__PURE__ */ new Set();
+  const resolve12 = (name2) => {
+    if (seen.has(name2)) return null;
+    seen.add(name2);
+    if (scope.props.has(name2)) return null;
+    if (PURE_SOURCE_GLOBALS.has(name2)) return null;
+    const constFree = scope.constants.get(name2);
+    if (constFree !== void 0) {
+      if (constFree === null) return `constant '${name2}' has no analyzable value`;
+      for (const inner of constFree) {
+        const failure = resolve12(inner);
+        if (failure) return failure;
+      }
+      return null;
+    }
+    const signal2 = scope.signals.get(name2);
+    if (signal2 !== void 0) {
+      if (signal2.initializerFreeIdentifiers === null) {
+        return `signal '${name2}' has no structured initializer to prove props/literal derivation`;
+      }
+      for (const inner of signal2.initializerFreeIdentifiers) {
+        const failure = resolve12(inner);
+        if (failure) return failure;
+      }
+      return null;
+    }
+    if (scope.memos.has(name2)) return `memo '${name2}' initializer is not analyzed by the v1 gate`;
+    if (scope.inert.has(name2)) return `'${name2}' is an import or local function`;
+    return `'${name2}' does not resolve to a prop, literal-derived const, or props/literal-derived signal`;
+  };
+  for (const name2 of names) {
+    const failure = resolve12(name2);
+    if (failure) return failure;
+  }
+  return null;
+}
+function classifyLazyBinding(args2) {
+  const { kind: kind2, slotId, free, rowLocalNames, indexParam, scope } = args2;
+  if (free === null) {
+    return {
+      kind: kind2,
+      slotId,
+      readsItem: true,
+      readsOuter: true,
+      reactiveOuterNames: [],
+      opaqueOuterNames: [UNKNOWN_IDENTIFIERS],
+      // An ASSUMPTION, not knowledge — which is precisely why
+      // `UNKNOWN_IDENTIFIERS` must keep refusing the loop: with no
+      // identifier set we cannot rule out an index read either, and
+      // `applyItem` / `applyOuter` have no index parameter to give it.
+      referencesIndex: false
+    };
+  }
+  let readsItem = false;
+  let referencesIndex = false;
+  const reactiveOuterNames = [];
+  const opaqueOuterNames = [];
+  for (const name2 of free) {
+    if (rowLocalNames.has(name2)) {
+      readsItem = true;
+      continue;
+    }
+    if (name2 === indexParam) {
+      referencesIndex = true;
+      continue;
+    }
+    if (INERT_BINDING_GLOBALS.has(name2)) continue;
+    if (scope.signals.has(name2) || scope.memos.has(name2)) {
+      if (!reactiveOuterNames.includes(name2)) reactiveOuterNames.push(name2);
+      continue;
+    }
+    const constFree = scope.constants.get(name2);
+    if (constFree !== void 0 && constFree !== null && constFree.size === 0) continue;
+    opaqueOuterNames.push(name2);
+  }
+  return {
+    kind: kind2,
+    slotId,
+    readsItem,
+    readsOuter: reactiveOuterNames.length > 0 || opaqueOuterNames.length > 0,
+    reactiveOuterNames,
+    opaqueOuterNames,
+    referencesIndex
+  };
+}
+var PURE_SOURCE_GLOBALS, INERT_BINDING_GLOBALS, UNKNOWN_IDENTIFIERS, NO;
+var init_lazy_row_eligibility = __esm({
+  "../jsx/src/ir-to-client-js/control-flow/plan/lazy-row-eligibility.ts"() {
+    "use strict";
+    PURE_SOURCE_GLOBALS = /* @__PURE__ */ new Set([
+      "Object",
+      "Array",
+      "JSON",
+      "Number",
+      "String",
+      "Boolean"
+    ]);
+    INERT_BINDING_GLOBALS = /* @__PURE__ */ new Set([
+      "Object",
+      "Array",
+      "JSON",
+      "Number",
+      "String",
+      "Boolean",
+      "Math",
+      "Date",
+      "Intl",
+      "Symbol",
+      "Map",
+      "Set",
+      "WeakMap",
+      "WeakSet",
+      "Promise",
+      "RegExp",
+      "Error",
+      "BigInt",
+      "console",
+      "undefined",
+      "NaN",
+      "Infinity",
+      "globalThis",
+      "parseInt",
+      "parseFloat",
+      "isNaN",
+      "isFinite",
+      "encodeURIComponent",
+      "decodeURIComponent",
+      "encodeURI",
+      "decodeURI"
+    ]);
+    UNKNOWN_IDENTIFIERS = "<unknown>";
+    NO = (reason2) => ({ eligible: false, reason: reason2 });
+  }
+});
+
+// ../jsx/src/ir-to-client-js/control-flow/plan/build-lazy-row.ts
+function buildLazyRowPlan(args2) {
+  return decideLazyRow(args2).plan;
+}
+function decideLazyRow(args2) {
+  const { loop, scope } = args2;
+  if (!scope) {
+    return { plan: null, decision: { eligible: false, reason: "no component scope info supplied" } };
+  }
+  const wrap = (expr) => wrapLoopParamAsAccessor(expr, loop.param, loop.paramBindings);
+  const rowLocalNames = /* @__PURE__ */ new Set([loop.param]);
+  for (const b of loop.paramBindings ?? []) rowLocalNames.add(b.name);
+  const classified = [];
+  const attrClass = /* @__PURE__ */ new Map();
+  loop.bindings.reactiveAttrs.forEach((attr, i) => {
+    const c = classifyLazyBinding({
+      kind: "attr",
+      slotId: attr.childSlotId,
+      free: attrFreeIdentifiers2(attr.expression),
+      rowLocalNames,
+      indexParam: args2.indexParam,
+      scope
+    });
+    attrClass.set(i, c);
+    classified.push(c);
+  });
+  const textClass = /* @__PURE__ */ new Map();
+  loop.bindings.reactiveTexts.forEach((text, i) => {
+    const c = classifyLazyBinding({
+      kind: "text",
+      slotId: text.slotId,
+      free: text.freeIdentifiers ?? null,
+      rowLocalNames,
+      indexParam: args2.indexParam,
+      scope
+    });
+    textClass.set(i, c);
+    classified.push(c);
+  });
+  const shape = {
+    callSite: args2.callSite,
+    flatMapLeafItem: args2.flatMapLeafItem,
+    anchored: args2.anchored,
+    bodyIsMultiRoot: loop.bodyIsMultiRoot ?? false,
+    hasExplicitKey: loop.key != null,
+    conditionalCount: loop.bindings.conditionals?.length ?? 0,
+    childRefCount: loop.bindings.refs?.length ?? 0,
+    nestedComponentCount: loop.nestedComponents?.length ?? 0,
+    innerLoopCount: loop.innerLoops?.length ?? 0,
+    hasChildComponent: "childComponent" in loop && loop.childComponent != null,
+    hasMapPreamble: args2.mapPreambleWrapped.length > 0,
+    preambleRegionCount: args2.preambleRegionCount,
+    hasParamUnwrap: args2.paramUnwrap.length > 0
+  };
+  const decision = lazyRowEligibility({
+    shape,
+    bindings: classified,
+    arraySourceIdentifiers: loopSourceIdentifiers(loop, args2.arrayExpr),
+    scope
+  });
+  if (!decision.eligible) return { plan: null, decision };
+  const attrSlotIds = [];
+  for (const attr of loop.bindings.reactiveAttrs) {
+    if (!attrSlotIds.includes(attr.childSlotId)) attrSlotIds.push(attr.childSlotId);
+  }
+  let ordinal = 0;
+  const attrs = loop.bindings.reactiveAttrs.map((attr, i) => {
+    const c = attrClass.get(i);
+    return {
+      slotId: attr.childSlotId,
+      attrName: attr.attrName,
+      wrappedExpression: wrap(attr.expression),
+      meta: pickAttrMeta(attr),
+      refIndex: attrSlotIds.indexOf(attr.childSlotId),
+      ordinal: ordinal++,
+      readsItem: c.readsItem,
+      readsOuter: c.readsOuter
+    };
+  });
+  const texts = loop.bindings.reactiveTexts.map((text, i) => {
+    const c = textClass.get(i);
+    return {
+      slotId: text.slotId,
+      wrappedExpression: wrap(text.expression),
+      ordinal: ordinal++,
+      // A text that classified as NEITHER item- nor outer-driven still gets
+      // applied on item change (harmless, dedup-guarded) rather than
+      // silently never being written. Anything the classifier did place in
+      // a list keeps exactly the classifier's answer.
+      readsItem: c.readsItem || !c.readsOuter,
+      readsOuter: c.readsOuter
+    };
+  });
+  const outerPrimeGetters = [];
+  for (const c of classified) {
+    for (const name2 of c.reactiveOuterNames) {
+      if (!outerPrimeGetters.includes(name2)) outerPrimeGetters.push(name2);
+    }
+  }
+  return {
+    plan: {
+      attrSlotIds,
+      attrs,
+      texts,
+      writerIndex: texts.length > 0 ? attrSlotIds.length : -1,
+      textNeedsRead: texts.some((t) => t.readsOuter),
+      lastCount: ordinal,
+      outerPrimeGetters,
+      hasOuter: attrs.some((a) => a.readsOuter) || texts.some((t) => t.readsOuter)
+    },
+    decision
+  };
+}
+function buildLazyRowScopeInfo(ctx2) {
+  const signals = /* @__PURE__ */ new Map();
+  for (const s of ctx2.signals) {
+    signals.set(s.getter, {
+      // `parsed` is the analyzer's structured initializer. Absent (or
+      // refused by `freeIdentifiers`) ⇒ unprovable, which the source gate
+      // treats as a hard stop rather than an assumption.
+      initializerFreeIdentifiers: s.parsed ? freeIdentifiers(s.parsed) : null
+    });
+  }
+  const memos = new Set(ctx2.memos.map((m) => m.name));
+  const props = /* @__PURE__ */ new Set([PROPS_PARAM]);
+  if (ctx2.propsObjectName) props.add(ctx2.propsObjectName);
+  for (const p of ctx2.propsParams) props.add(p.name);
+  const constants = /* @__PURE__ */ new Map();
+  for (const c of ctx2.localConstants) {
+    constants.set(c.name, c.freeIdentifiers ?? null);
+  }
+  const inert = /* @__PURE__ */ new Set();
+  for (const f of ctx2.localFunctions) inert.add(f.name);
+  for (const imp of ctx2.imports) {
+    if (imp.isTypeOnly) continue;
+    for (const spec of imp.specifiers) inert.add(spec.alias || spec.name);
+  }
+  return { signals, memos, props, constants, inert, profile: ctx2.profile };
+}
+function attrFreeIdentifiers2(expression) {
+  if (!expression || expression.trim().length === 0) return /* @__PURE__ */ new Set();
+  try {
+    return freeIdentifiers(parseExpression(expression));
+  } catch {
+    return null;
+  }
+}
+function loopSourceIdentifiers(loop, arrayExpr) {
+  if (!loop.arrayFreeIdentifiers) return null;
+  const names = new Set(loop.arrayFreeIdentifiers);
+  for (const name2 of extractFreeIdentifiersFromText(arrayExpr)) names.add(name2);
+  return names;
+}
+var init_build_lazy_row = __esm({
+  "../jsx/src/ir-to-client-js/control-flow/plan/build-lazy-row.ts"() {
+    "use strict";
+    init_expression_parser();
+    init_types();
+    init_csr_substitute();
+    init_utils();
+    init_lazy_row_eligibility();
+  }
+});
+
 // ../jsx/src/ir-to-client-js/control-flow/plan/build-branch-loop.ts
-function buildBranchLoopPlan(loop, profileComponentName) {
+function buildBranchLoopPlan(loop, profileComponentName, lazyScope) {
   const containerSlotId = loop.containerSlotId;
   const cv = varSlotId(containerSlotId);
   const containerVar = `__loop_${cv}`;
@@ -18511,6 +18888,13 @@ function buildBranchLoopPlan(loop, profileComponentName) {
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(loop.param, loop.paramBindings);
   const hasReactiveEffects = loop.bindings.reactiveAttrs.length > 0 || loop.bindings.reactiveTexts.length > 0 || loop.bindings.conditionals.length > 0;
   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, void 0, 1, [{ param: loop.param, bindings: loop.paramBindings }], void 0, true)
+  }) : "";
+  const preambleRegions = buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings);
   const plan = {
     kind: "plain",
     rowConstruction: "string-template",
@@ -18518,17 +18902,27 @@ function buildBranchLoopPlan(loop, profileComponentName) {
     containerVar,
     markerId: loop.markerId,
     flatMapLeafItem: fm ? true : void 0,
-    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, void 0, 1, [{ param: loop.param, bindings: loop.paramBindings }], void 0, 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
+    }) ?? void 0,
     template: loop.template,
     reactiveEffects: hasReactiveEffects ? buildReactiveEffectsPlan({
       attrs: loop.bindings.reactiveAttrs,
@@ -18540,7 +18934,7 @@ function buildBranchLoopPlan(loop, profileComponentName) {
     }) : 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}` : void 0
   };
@@ -18553,6 +18947,7 @@ var init_build_branch_loop = __esm({
     init_build_composite_loop();
     init_build_event_delegation();
     init_build_reactive_effects();
+    init_build_lazy_row();
     init_shared();
     init_html_template();
   }
@@ -18609,13 +19004,13 @@ function buildArmBody(branch, options2) {
       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, options2.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: options2.eventNameMode, profileComponentName: pc })
+      (c) => buildInsertPlan(c, { scope: { kind: "branchScope" }, eventNameMode: options2.eventNameMode, profileComponentName: pc, lazyScope: options2.lazyScope })
     )
   };
 }
@@ -19008,7 +19403,7 @@ function stringifyBranchEventBindings(lines, plan, indent) {
 }
 function stringifyBranchChildComponentInits(lines, plan, indent) {
   for (const init of plan) {
-    lines.push(`${indent}{ let __c = qsa(__branchScope, ${init.selector}); if (!__c) { const __ph = __branchScope.querySelector('[${BF_PLACEHOLDER}="${init.placeholderId}"]'); if (__ph) { __c = createComponent('${nameForRegistryRef(init.name)}', ${init.propsExpr}); __ph.replaceWith(__c) } } if (__c) initChild('${nameForRegistryRef(init.name)}', __c, ${init.propsExpr}) }`);
+    lines.push(`${indent}{ let __c = qsa(__branchScope, ${init.selector}); if (!__c) { const __ph = __branchScope.querySelector('[${BF_PLACEHOLDER}="${init.placeholderId}"]'); if (__ph) { __c = createComponent('${nameForRegistryRef(init.name)}', ${init.propsExpr}, undefined, undefined, __ph) } } if (__c) initChild('${nameForRegistryRef(init.name)}', __c, ${init.propsExpr}) }`);
   }
 }
 function stringifyBranchInnerLoops(lines, plan, indent, pc) {
@@ -19356,6 +19751,179 @@ var init_component_loop = __esm({
   }
 });
 
+// ../jsx/src/ir-to-client-js/control-flow/stringify/lazy-row.ts
+function stringifyLazyRowLoop(lines, o) {
+  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;
+  const rwDoor = lazyRow.textNeedsRead;
+  const paths = o.skeletonPaths;
+  const useHoisted = Boolean(o.skeletonTemplate);
+  if (useHoisted) emitHoistedTemplateDecl(lines, indent, tplVar, o.skeletonTemplate);
+  const textPathVar = useHoisted && paths && lazyRow.texts.length > 0 ? `__lzp_${mid}` : null;
+  if (textPathVar) {
+    const arrays = lazyRow.texts.map((t) => `[${(paths.textMarkerPaths.get(t.slotId) ?? []).join(", ")}]`);
+    lines.push(`${indent}const ${textPathVar} = [${arrays.join(", ")}]`);
+  }
+  let adoptedPlanVar = null;
+  let freshPlanVar = null;
+  if (lazyRow.texts.length > 0) {
+    adoptedPlanVar = `__lzs_${mid}`;
+    const adoptedSlots = lazyRow.texts.map((t) => ({ id: t.slotId, kind: "text", path: [] }));
+    lines.push(`${indent}const ${adoptedPlanVar} = ${claimPlanLiteral(adoptedSlots)}`);
+    if (textPathVar) {
+      freshPlanVar = `__lzsc_${mid}`;
+      const freshSlots = lazyRow.texts.map((t, i) => ({
+        id: t.slotId,
+        kind: "text",
+        path: [],
+        pathExpr: `${textPathVar}[${i}]`
+      }));
+      lines.push(`${indent}const ${freshPlanVar} = ${claimPlanLiteral(freshSlots)}`);
+    } else {
+      freshPlanVar = adoptedPlanVar;
+    }
+  }
+  if (hasRefs) {
+    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}}`);
+  }
+  const call = `mapArrayLazy(() => ${o.arrayExpr}, ${o.containerVar}, ${o.keyFn}, {`;
+  lines.push(`${indent}${o.guardContainer ? `if (${o.containerVar}) ` : ""}${call}`);
+  const b1 = `${indent}  `;
+  const b2 = `${indent}    `;
+  lines.push(`${b1}createRow: (__e, ${o.indexParam}) => {`);
+  lines.push(`${b2}const ${paramHead} = () => __e.item`);
+  const cloneExpr = useHoisted ? hoistedCloneExpr(tplVar, o.skeletonTemplate) : `(() => { ${emitTemplateCloneInline(o.template)} })()`;
+  lines.push(`${b2}const __el = ${cloneExpr}`);
+  if (hasRefs) {
+    lines.push(`${b2}const __r = __e.refs = [${refParts(lazyRow, "__el", useHoisted ? paths ?? null : null, freshPlanVar).join(", ")}]`);
+  }
+  if (hasBindings) {
+    lines.push(`${b2}const __l = __e.last = []`);
+    for (const a of lazyRow.attrs) emitAttrBinding(lines, b2, a, "create");
+    const createDoor = `__r[${lazyRow.writerIndex}]`;
+    for (const t of lazyRow.texts) emitTextBinding(lines, b2, t, createDoor, "create", rwDoor);
+  }
+  lines.push(`${b2}return __el`);
+  lines.push(`${b1}},`);
+  const itemAttrs = lazyRow.attrs.filter((a) => a.readsItem);
+  const itemTexts = lazyRow.texts.filter((t) => t.readsItem);
+  if (itemAttrs.length === 0 && itemTexts.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 __l = __e.last ?? (__e.last = [])`);
+    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);
+    }
+    lines.push(`${b1}},`);
+  }
+  const outerAttrs = lazyRow.attrs.filter((a) => a.readsOuter);
+  const outerTexts = lazyRow.texts.filter((t) => t.readsOuter);
+  if (outerAttrs.length > 0 || outerTexts.length > 0) {
+    const b3 = `${indent}      `;
+    lines.push(`${b1}applyOuter: (__es, __seed) => {`);
+    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 __l = __e.last ?? (__e.last = [])`);
+    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);
+    }
+    lines.push(`${b2}}`);
+    lines.push(`${b1}},`);
+  }
+  lines.push(`${indent}}, '${o.markerId}')`);
+}
+function refParts(lazyRow, elVar, skeletonPaths, planVar, deferDoor = false) {
+  const parts = [];
+  for (const slotId of lazyRow.attrSlotIds) {
+    const path25 = skeletonPaths?.elementPaths.get(slotId);
+    parts.push(path25 ? pathExpr(elVar, path25) : `qsa(${elVar}, '[bf="${slotId}"]')`);
+  }
+  if (lazyRow.texts.length > 0) {
+    parts.push(deferDoor ? "null" : `${doorCtor(lazyRow)}(${elVar}, ${planVar})`);
+  }
+  return parts;
+}
+function doorCtor(lazyRow) {
+  return lazyRow.textNeedsRead ? "lazyClaimSlots" : "lazySlots";
+}
+function doorAccess(lazyRow, writerIndex, adoptedPlanVar) {
+  const slot = `__r[${writerIndex}]`;
+  return `${slot} ?? (${slot} = ${doorCtor(lazyRow)}(__e.primaryEl, ${adoptedPlanVar}))`;
+}
+function dedupGuard(ordinal) {
+  return `!(${ordinal} in __l) || !Object.is(__l[${ordinal}], __x)`;
+}
+function emitAttrBinding(lines, ind, a, mode2) {
+  lines.push(`${ind}{ const __t = __r[${a.refIndex}]`);
+  lines.push(`${ind}if (__t) {`);
+  lines.push(`${ind}  const __x = ${a.wrappedExpression}`);
+  const guard = mode2 === "create" ? null : mode2 === "item" ? dedupGuard(a.ordinal) : `__seed ? (${seedDiffersExpr("__t", a)}) : (${dedupGuard(a.ordinal)})`;
+  const writeIndent = guard ? `${ind}    ` : `${ind}  `;
+  if (guard) lines.push(`${ind}  if (${guard}) {`);
+  for (const stmt of emitAttrUpdate("__t", a.attrName, "__x", a.meta)) {
+    lines.push(`${writeIndent}${stmt}`);
+  }
+  if (guard) lines.push(`${ind}  }`);
+  lines.push(`${ind}  __l[${a.ordinal}] = __x`);
+  lines.push(`${ind}} }`);
+}
+function emitTextBinding(lines, ind, t, doorExpr, mode2, rwDoor) {
+  lines.push(`${ind}{ const __x = ${t.wrappedExpression}`);
+  const writeOf = (valueExpr) => rwDoor ? `${doorExpr}.write('${t.slotId}', ${valueExpr})` : `${doorExpr}('${t.slotId}', ${valueExpr})`;
+  if (mode2 === "outer") {
+    lines.push(`${ind}if (__seed) {`);
+    lines.push(`${ind}  const __s = textOrNode(__x)`);
+    lines.push(`${ind}  if (${doorExpr}.read('${t.slotId}') !== __s) ${writeOf("__s")}`);
+    lines.push(`${ind}} else if (${dedupGuard(t.ordinal)}) ${writeOf("textOrNode(__x)")}`);
+  } else if (mode2 === "item") {
+    lines.push(`${ind}if (${dedupGuard(t.ordinal)}) ${writeOf("textOrNode(__x)")}`);
+  } else {
+    lines.push(`${ind}${writeOf("textOrNode(__x)")}`);
+  }
+  lines.push(`${ind}__l[${t.ordinal}] = __x }`);
+}
+function seedDiffersExpr(target2, a) {
+  const html = toHTMLAttrName(a.attrName);
+  if (a.attrName === "dangerouslySetInnerHTML" || html === "dangerouslySetInnerHTML") return "true";
+  if (html === "style") return `${target2}.getAttribute('style') !== styleToCss(__x)`;
+  if (html === "class") return `${target2}.getAttribute('class') !== (__x != null ? String(__x) : null)`;
+  if (html === "value") return `${target2}.value !== String(__x)`;
+  if (isBooleanAttr(html)) return `${target2}.${html} !== !!(__x)`;
+  if (a.meta.presenceOrUndefined) {
+    const written = html.startsWith("aria-") ? "true" : "";
+    return `${target2}.getAttribute('${html}') !== (__x ? '${written}' : null)`;
+  }
+  return `${target2}.getAttribute('${html}') !== (__x != null ? String(__x) : null)`;
+}
+var init_lazy_row = __esm({
+  "../jsx/src/ir-to-client-js/control-flow/stringify/lazy-row.ts"() {
+    "use strict";
+    init_html_constants();
+    init_emit_reactive();
+    init_utils();
+    init_claim_plan();
+    init_skeleton_paths();
+    init_template_parse();
+  }
+});
+
 // ../jsx/src/ir-to-client-js/control-flow/stringify/loop.ts
 function emitLoopChildRefs(lines, refs, opts) {
   if (refs.length === 0) return;
@@ -19432,6 +20000,23 @@ function stringifyPlainLoop(lines, plan, topIndent = "  ") {
     stringifyAnchoredLoop(lines, plan, topIndent, anchorKeyExpr);
     return;
   }
+  if (plan.lazyRow) {
+    stringifyLazyRowLoop(lines, {
+      indent: topIndent,
+      containerVar,
+      guardContainer: false,
+      markerId,
+      arrayExpr,
+      keyFn,
+      paramHead,
+      indexParam,
+      template,
+      skeletonTemplate,
+      skeletonPaths: plan.skeletonPaths,
+      lazyRow: plan.lazyRow
+    });
+    return;
+  }
   const hoistedTpl = !bodyIsMultiRoot && skeletonTemplate ? skeletonTemplate : null;
   const tplVar = `__tpl_${markerId.replace(/[^A-Za-z0-9_$]/g, "_")}`;
   if (hoistedTpl) {
@@ -19619,6 +20204,7 @@ var init_loop = __esm({
     init_component_loop();
     init_composite_loop();
     init_claim_plan();
+    init_lazy_row();
   }
 });
 
@@ -20052,6 +20638,23 @@ function emitPlain(lines, plan) {
     stringifyEventDelegation(lines, eventDelegation);
     return;
   }
+  if (plan.lazyRow) {
+    stringifyLazyRowLoop(lines, {
+      indent: "        ",
+      containerVar,
+      guardContainer: true,
+      markerId,
+      arrayExpr,
+      keyFn,
+      paramHead,
+      indexParam,
+      template,
+      lazyRow: plan.lazyRow
+    });
+    lines.push(`      }))`);
+    stringifyEventDelegation(lines, eventDelegation);
+    return;
+  }
   if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0 && preambleRegions.length === 0) {
     const cloneExpr = emitTemplateCloneInline(template);
     if (mapPreambleWrapped) {
@@ -20097,6 +20700,7 @@ var init_branch_loop = __esm({
     init_reactive_effects();
     init_template_parse();
     init_loop();
+    init_lazy_row();
   }
 });
 
@@ -20283,7 +20887,7 @@ var init_build_component_loop = __esm({
 // ../jsx/src/ir-to-client-js/control-flow/plan/build-loop.ts
 function buildLoopPlan(elem, opts) {
   if (elem.bodyIsItemConditional) {
-    return buildPlainLoopPlan(elem, opts.profileComponentName);
+    return buildPlainLoopPlan(elem, opts.profileComponentName, opts.lazyScope);
   }
   if (elem.isStaticArray) {
     return buildStaticLoopPlan(elem, opts.unsafeLocalNames, opts.profileComponentName);
@@ -20295,9 +20899,9 @@ function buildLoopPlan(elem, opts) {
   if (elem.childComponent) {
     return buildComponentLoopPlan(elem, opts.profileComponentName);
   }
-  return buildPlainLoopPlan(elem, opts.profileComponentName);
+  return buildPlainLoopPlan(elem, opts.profileComponentName, opts.lazyScope);
 }
-function buildPlainLoopPlan(elem, profileComponentName) {
+function buildPlainLoopPlan(elem, profileComponentName, lazyScope) {
   const wrap = (expr) => wrapLoopParamAsAccessor(expr, elem.param, elem.paramBindings);
   const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(elem.param, elem.paramBindings);
   const hasReactive2 = elem.bindings.reactiveAttrs.length > 0 || elem.bindings.reactiveTexts.length > 0 || elem.bindings.conditionals.length > 0;
@@ -20326,30 +20930,48 @@ function buildPlainLoopPlan(elem, profileComponentName) {
       preambleRegions: []
     };
   }
+  const arrayExpr = buildChainedArrayExpr(elem);
+  const indexParam = elem.index || "__idx";
+  const mapPreambleWrapped = elem.preamble ? renderPreamble(elem.preamble, {
+    transformJs: wrap,
+    renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, [{ param: elem.param, bindings: elem.paramBindings }], void 0, true)
+  }) : "";
+  const preambleRegions = buildPreambleRegionPlans(elem.preambleRegions, elem.param, elem.paramBindings);
   return {
     kind: "plain",
     rowConstruction: "string-template",
     containerVar: `_${varSlotId(elem.slotId)}`,
     markerId: elem.markerId,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${elem.slotId}` : void 0,
-    arrayExpr: buildChainedArrayExpr(elem),
+    arrayExpr,
     keyFn: loopKeyFn(elem),
     paramHead,
     paramUnwrap,
-    indexParam: elem.index || "__idx",
+    indexParam,
+    // Lazy row graph (§9, L3). `null` for every ineligible loop, which then
+    // keeps the eager emission below byte-for-byte.
+    lazyRow: buildLazyRowPlan({
+      loop: elem,
+      arrayExpr,
+      indexParam,
+      paramUnwrap,
+      mapPreambleWrapped,
+      preambleRegionCount: preambleRegions.length,
+      callSite: "plain",
+      flatMapLeafItem: false,
+      anchored: elem.bodyIsItemConditional ?? false,
+      scope: lazyScope
+    }) ?? void 0,
     // Stage 3 / D4 — js segments get the loop-param accessor wrap; jsx leaves
     // render as HTML-string templates under this loop's param context so a
     // leaf that reads the item (`r`) becomes `r()`.
-    mapPreambleWrapped: elem.preamble ? renderPreamble(elem.preamble, {
-      transformJs: wrap,
-      renderLeaf: (ir) => irToHtmlTemplate(ir, void 0, 1, [{ param: elem.param, bindings: elem.paramBindings }], void 0, true)
-    }) : "",
+    mapPreambleWrapped,
     template: elem.template,
     skeletonTemplate: elem.skeletonTemplate,
     skeletonPaths: elem.skeletonPaths,
     reactiveEffects: hasReactive2 ? buildLoopReactiveEffectsPlan(elem, profileComponentName) : null,
     childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
-    preambleRegions: buildPreambleRegionPlans(elem.preambleRegions, elem.param, elem.paramBindings),
+    preambleRegions,
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,
     anchored: elem.bodyIsItemConditional ?? false,
     // Fall back to the iteration index when the loop has no key. A whole-item
@@ -20411,6 +21033,7 @@ var init_build_loop = __esm({
     init_utils();
     init_shared();
     init_build_reactive_effects();
+    init_build_lazy_row();
     init_build_component_loop();
     init_build_composite_loop();
     init_html_template();
@@ -20421,7 +21044,7 @@ var init_build_loop = __esm({
 function emitConditionalUpdates(lines, ctx2) {
   const profileComponentName = ctx2.profile ? ctx2.componentName : void 0;
   for (const elem of ctx2.conditionalElements) {
-    const plan = buildInsertPlan(elem, { scope: { kind: "top" }, eventNameMode: "dom", profileComponentName });
+    const plan = buildInsertPlan(elem, { scope: { kind: "top" }, eventNameMode: "dom", profileComponentName, lazyScope: buildLazyRowScopeInfo(ctx2) });
     stringifyInsert(lines, plan, { leadingIndent: "  ", bodyIndent: "      " });
     lines.push("");
   }
@@ -20429,17 +21052,19 @@ function emitConditionalUpdates(lines, ctx2) {
 function emitClientOnlyConditionals(lines, ctx2) {
   const profileComponentName = ctx2.profile ? ctx2.componentName : void 0;
   for (const elem of ctx2.clientOnlyConditionals) {
-    const plan = buildInsertPlan(elem, { scope: { kind: "top" }, eventNameMode: "raw", profileComponentName });
+    const plan = buildInsertPlan(elem, { scope: { kind: "top" }, eventNameMode: "raw", profileComponentName, lazyScope: buildLazyRowScopeInfo(ctx2) });
     lines.push(`  // @client conditional: ${elem.slotId}`);
     stringifyInsert(lines, plan, { leadingIndent: "  ", bodyIndent: "      " });
     lines.push("");
   }
 }
 function emitLoopUpdates(lines, ctx2, unsafeLocalNames) {
+  const lazyScope = buildLazyRowScopeInfo(ctx2);
   for (const elem of ctx2.loopElements) {
     const plan = buildLoopPlan(elem, {
       unsafeLocalNames,
-      profileComponentName: ctx2.profile ? ctx2.componentName : void 0
+      profileComponentName: ctx2.profile ? ctx2.componentName : void 0,
+      lazyScope
     });
     internalInvariant(
       !(elem.preamble && elem.preamble.builderNames.length > 0 && plan.rowConstruction === "dom-ops"),
@@ -20467,6 +21092,7 @@ var init_control_flow = __esm({
     init_build_insert();
     init_insert();
     init_build_loop();
+    init_build_lazy_row();
     init_loop();
     init_build_event_delegation();
     init_event_delegation();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "CLI for agent-driven UI component discovery and scaffolding",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,11 +29,11 @@
   "dependencies": {
     "esbuild": "^0.25.0",
     "typescript": "^5.0.0",
-    "@barefootjs/client": "0.27.0",
-    "@barefootjs/shared": "0.27.0"
+    "@barefootjs/client": "0.28.0",
+    "@barefootjs/shared": "0.28.0"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.27.0",
+    "@barefootjs/jsx": "0.28.0",
     "@types/node": "^22.0.0",
     "@happy-dom/global-registrator": "^20.0.11",
     "happy-dom": "^20.0.11"