@barefootjs/cli 0.5.0 → 0.5.2

package/dist/docs/core/llms.txt

@@ -12,6 +12,7 @@
 
 ## Reactivity
 
+- [batch](https://barefootjs.dev/docs/reactivity/batch.md): Groups multiple signal writes so dependent effects and memos run once, after all writes complete.
 - [createEffect](https://barefootjs.dev/docs/reactivity/create-effect.md): Runs a function and re-runs it whenever its tracked signal dependencies change.
 - [createMemo](https://barefootjs.dev/docs/reactivity/create-memo.md): Creates a cached derived value that recomputes only when its dependencies change.
 - [createSignal](https://barefootjs.dev/docs/reactivity/create-signal.md): Creates a reactive getter/setter pair for managing state.

package/dist/docs/core/reactivity/batch.md

@@ -0,0 +1,135 @@
+---
+title: batch
+description: Groups multiple signal writes so dependent effects and memos run once, after all writes complete.
+---
+
+# batch
+
+Groups multiple signal writes so that dependent effects and memos run **once**,
+after all the writes inside the batch complete — instead of once per write.
+
+```tsx
+import { batch } from '@barefootjs/client'
+
+batch<T>(fn: () => T): T
+```
+
+Returns the value produced by `fn`.
+
+## Default behavior (no batch)
+
+BarefootJS propagates updates **synchronously**: each setter call immediately
+re-runs every subscriber. This keeps reads-after-writes predictable — after a
+setter returns, derived memos, effects, and the DOM already reflect the new value.
+
+The cost is that writing N signals that share a subscriber re-runs that
+subscriber N times, and the subscriber briefly observes intermediate states
+where some signals are updated and others are not:
+
+```tsx
+const [x, setX] = createSignal(40)
+const [y, setY] = createSignal(60)
+
+createEffect(() => {
+  // depends on both x and y
+  send({ x: x(), y: y() })
+})
+
+setX(70) // effect runs — observes x=70, y=60 (intermediate)
+setY(30) // effect runs again — observes x=70, y=30
+```
+
+Beyond its initial run on creation, the effect ran twice more — once per write —
+and saw a transient `x=70, y=60` state.
+
+## With batch
+
+```tsx
+batch(() => {
+  setX(70)
+  setY(30)
+})
+// effect runs once, observing x=70, y=30
+```
+
+Inside `batch`, writes are collected and dependent subscribers are de-duplicated,
+so each runs **exactly once** after the batch ends — and never observes an
+intermediate, half-updated state.
+
+## When to use
+
+When a single handler updates several signals that feed shared effects/memos,
+`batch` collapses the work into one update pass — and keeps the subscriber from
+running while a cross-field invariant is temporarily broken:
+
+```tsx
+const reset = () => {
+  batch(() => {
+    setName('')
+    setEmail('')
+    setAge(0)
+    // ...20 more fields
+  })
+  // every subscriber ran once, not once-per-field
+}
+```
+
+## Caveats
+
+### Derived values are stale *inside* the batch
+
+`batch` defers the work that recomputes derived values. Plain signal reads return
+the new value immediately, but **memos and effect-driven values stay stale until
+the batch ends**:
+
+```tsx
+const [n, setN] = createSignal(1)
+const doubled = createMemo(() => n() * 2)
+
+batch(() => {
+  setN(10)
+  n()       // 10  — plain signal read is fresh
+  doubled() // 2   — STALE; the memo hasn't recomputed yet
+})
+doubled()   // 20  — recomputed after the batch ends
+```
+
+If you need the recomputed value, read it after the batch.
+
+### `await` escapes the batch
+
+`batch` only covers the **synchronous** portion of `fn`. Wrapping an async
+function in `batch` groups only the writes before the first `await` — everything
+after runs ungrouped, and the promise `batch` returns is easy to leave floating.
+
+Instead, wrap each synchronous group of writes in its own `batch`, with `await`
+between the groups:
+
+```tsx
+const onSubmit = async () => {
+  batch(() => {
+    setLoading(true)
+    setError(null)
+  })
+
+  try {
+    const result = await save()
+    batch(() => {
+      setLoading(false)
+      setResult(result)
+    })
+  } catch (err) {
+    batch(() => {
+      setLoading(false)
+      setError(err)
+    })
+  }
+}
+```
+
+## Note
+
+`batch` is an **opt-in** optimization. Forgetting it is never a correctness bug —
+code still works, just with extra subscriber runs. Reach for `batch` when a
+handler writes many signals that share subscribers, or when an effect must not
+observe a partially-updated state.

package/dist/docs/core/reactivity.md

@@ -9,7 +9,7 @@ All reactive primitives are imported from `@barefootjs/client`:
 
 ```tsx
 "use client"
-import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack } from '@barefootjs/client'
+import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack, batch } from '@barefootjs/client'
 ```
 
 ## API Reference
@@ -22,6 +22,7 @@ import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack } f
 | [`onMount`](./reactivity/on-mount.md) | Run once on component initialization |
 | [`onCleanup`](./reactivity/on-cleanup.md) | Register cleanup for effects and lifecycle |
 | [`untrack`](./reactivity/untrack.md) | Read signals without tracking dependencies |
+| [`batch`](./reactivity/batch.md) | Group signal writes so subscribers run once |
 
 ## Guides
 

package/dist/index.js

@@ -359,13 +359,16 @@ var init_js_scanner = __esm({
 });
 
 // ../shared/src/markers.ts
+function loopItemMarker(key) {
+  return `${BF_LOOP_ITEM}:${key}`;
+}
 function loopStartMarker(markerId) {
   return `${BF_LOOP_START}:${markerId}`;
 }
 function loopEndMarker(markerId) {
   return `${BF_LOOP_END}:${markerId}`;
 }
-var BF_SCOPE, BF_SLOT, BF_HOST, BF_AT, BF_COND, BF_LOOP_START, BF_LOOP_END, BF_KEY, BF_KEY_PREFIX, BF_PLACEHOLDER, BF_PARENT_SCOPE_PLACEHOLDER;
+var BF_SCOPE, BF_SLOT, BF_HOST, BF_AT, BF_COND, BF_LOOP_START, BF_LOOP_END, BF_LOOP_ITEM, BF_KEY, BF_KEY_PREFIX, BF_PLACEHOLDER, BF_PARENT_SCOPE_PLACEHOLDER;
 var init_markers = __esm({
   "../shared/src/markers.ts"() {
     "use strict";
@@ -376,6 +379,7 @@ var init_markers = __esm({
     BF_COND = "bf-c";
     BF_LOOP_START = "bf-loop";
     BF_LOOP_END = "bf-/loop";
+    BF_LOOP_ITEM = "bf-loop-i";
     BF_KEY = "data-key";
     BF_KEY_PREFIX = "data-key-";
     BF_PLACEHOLDER = "data-bf-ph";
@@ -1376,6 +1380,9 @@ function buildSpreadAttrsMergeCall(args2) {
   }
   return `\${spreadAttrs({${objMembers.join(", ")}})}`;
 }
+function itemAnchorTemplate(keyExpr) {
+  return `<!--${loopItemMarker("${" + keyExpr + "}")}-->`;
+}
 function irToHtmlTemplate(node, restSpreadNames, loopDepth = 0, loopParams, branchSlotsVar, insideLoop = false, inHoistedChildren = false) {
   const recurse = (n) => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, insideLoop, inHoistedChildren);
   const wrapExpr = (expr) => wrapExprWithLoopParams(expr, loopParams);
@@ -1467,7 +1474,10 @@ function irToHtmlTemplate(node, restSpreadNames, loopDepth = 0, loopParams, bran
     }
     case "loop": {
       const innerRecurse = (n) => irToHtmlTemplate(n, restSpreadNames, loopDepth + 1, loopParams, branchSlotsVar, insideLoop);
-      const childTemplate = node.children.map(innerRecurse).join("");
+      let childTemplate = node.children.map(innerRecurse).join("");
+      if (node.bodyIsItemConditional && node.key) {
+        childTemplate = `${itemAnchorTemplate(node.key)}${childTemplate}`;
+      }
       const indexParam = node.index ? `, ${node.index}` : "";
       const rawChainedArray = applyLoopChain(node);
       const { array: iterArray, callbackParam } = applyIterationShape(node, rawChainedArray, indexParam);
@@ -2030,7 +2040,10 @@ function generateCsrTemplateWithOpts(node, opts) {
       return `\${renderChild('${nameForRegistryRef(node.name)}', ${propsExpr}${keyArg || (slotArg ? ", undefined" : "")}${slotArg})}`;
     }
     case "loop": {
-      const childTemplate = node.children.map(recurseInLoop).join("");
+      let childTemplate = node.children.map(recurseInLoop).join("");
+      if (node.bodyIsItemConditional && node.key) {
+        childTemplate = `${itemAnchorTemplate(node.key)}${childTemplate}`;
+      }
       const indexParam = node.index ? `, ${node.index}` : "";
       const chainedTemplateArray = node.sortComparator || node.filterPredicate ? applyLoopChain(node, node.templateArray) : node.templateArray;
       const rawArrayExpr = transformExpr(node.array, chainedTemplateArray);
@@ -2437,6 +2450,24 @@ function getSourceLocation(node, sourceFile, filePath) {
     }
   };
 }
+function membersToProperties(members, sourceFile) {
+  return members.filter(ts6.isPropertySignature).map((member) => ({
+    name: propertyNameText(member.name, sourceFile),
+    type: typeNodeToTypeInfo(member.type, sourceFile) ?? {
+      kind: "unknown",
+      raw: "unknown"
+    },
+    optional: !!member.questionToken,
+    readonly: !!member.modifiers?.some(
+      (m) => m.kind === ts6.SyntaxKind.ReadonlyKeyword
+    )
+  }));
+}
+function propertyNameText(name, sourceFile) {
+  if (!name) return "";
+  if (ts6.isStringLiteral(name) || ts6.isNumericLiteral(name)) return name.text;
+  return name.getText(sourceFile);
+}
 function typeNodeToTypeInfo(typeNode, sourceFile) {
   if (!typeNode) return null;
   const raw = typeNode.getText(sourceFile);
@@ -2475,20 +2506,21 @@ function typeNodeToTypeInfo(typeNode, sourceFile) {
     return {
       kind: "object",
       raw,
-      properties: typeNode.members.filter(ts6.isPropertySignature).map((member) => ({
-        name: member.name?.getText(sourceFile) ?? "",
-        type: typeNodeToTypeInfo(member.type, sourceFile) ?? {
-          kind: "unknown",
-          raw: "unknown"
-        },
-        optional: !!member.questionToken,
-        readonly: !!member.modifiers?.some(
-          (m) => m.kind === ts6.SyntaxKind.ReadonlyKeyword
-        )
-      }))
+      properties: membersToProperties(typeNode.members, sourceFile)
     };
   }
   if (ts6.isTypeReferenceNode(typeNode)) {
+    const refName = ts6.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : "";
+    if ((refName === "Array" || refName === "ReadonlyArray") && typeNode.typeArguments?.length === 1) {
+      return {
+        kind: "array",
+        raw,
+        elementType: typeNodeToTypeInfo(typeNode.typeArguments[0], sourceFile) ?? {
+          kind: "unknown",
+          raw: "unknown"
+        }
+      };
+    }
     return {
       kind: "interface",
       raw
@@ -3666,14 +3698,17 @@ function collectInterfaceDefinition(node, ctx2) {
     kind: "interface",
     name: node.name.text,
     definition: node.getText(ctx2.sourceFile),
+    properties: membersToProperties(node.members, ctx2.sourceFile),
     loc: getSourceLocation(node, ctx2.sourceFile, ctx2.filePath)
   });
 }
 function collectTypeAliasDefinition(node, ctx2) {
+  const properties = ts7.isTypeLiteralNode(node.type) ? membersToProperties(node.type.members, ctx2.sourceFile) : void 0;
   ctx2.typeDefinitions.push({
     kind: "type",
     name: node.name.text,
     definition: node.getText(ctx2.sourceFile),
+    properties,
     loc: getSourceLocation(node, ctx2.sourceFile, ctx2.filePath)
   });
 }
@@ -5869,7 +5904,7 @@ function checkSupport(expr) {
           return {
             supported: false,
             level: "L5_UNSUPPORTED",
-            reason: `Higher-order method '${methodName}()' requires client-side evaluation. Use @client directive or pre-compute in Go.`
+            reason: `Method '${methodName}()' has no template lowering and requires client-side evaluation. Wrap the expression in /* @client */ to defer it to hydration, or pre-compute the value before rendering.`
           };
         }
       }
@@ -6159,7 +6194,7 @@ var init_expression_parser = __esm({
       "some",
       "forEach",
       "flatMap",
-      "flat"
+      "flat",
       // #1448 Tier A — Array methods. Each method PR adds the lowering
       // (typically a new `array-method` variant or runtime helper) and
       // removes its row here. See packages/adapter-tests/fixtures/methods/.
@@ -6189,6 +6224,34 @@ var init_expression_parser = __esm({
       // `bf_lower` / `bf_upper` (Go) and Perl's native `lc` / `uc` (Mojo).
       // `trim` lowers via the `array-method` IR + `bf_trim` (Go) and a
       // Perl regex strip (Mojo).
+      //
+      // #1448 follow-up — String methods that have NO lowering yet. These
+      // were previously absent from this gate, so `isSupported` reported
+      // them "supported" and the adapters emitted a raw method call
+      // (`{{.Name.StartsWith "a"}}` on Go, `$name->{startsWith}('a')` on
+      // Mojo) with no build diagnostic — a silent footgun that only
+      // surfaced as a crash at template-render time. Listing them here
+      // makes the build fail loudly with BF101 (the same treatment the
+      // unsupported array methods above get), pointing users at the
+      // `/* @client */` escape hatch. Each name drops off as its lowering
+      // lands. See #1448 "Unsupported string methods" Tier B / Tier C.
+      "split",
+      "startsWith",
+      "endsWith",
+      "replace",
+      "replaceAll",
+      "repeat",
+      "padStart",
+      "padEnd",
+      "charAt",
+      "charCodeAt",
+      "codePointAt",
+      "normalize",
+      "substring",
+      "substr",
+      "match",
+      "matchAll",
+      "search"
     ]);
   }
 });
@@ -7385,6 +7448,22 @@ function containsJsxInExpression(node) {
   }
   return ts11.forEachChild(node, containsJsxInExpression) ?? false;
 }
+function callsJsxHelper(node, ctx2) {
+  let found = false;
+  const visit3 = (n) => {
+    if (found) return;
+    if (ts11.isCallExpression(n) && ts11.isIdentifier(n.expression)) {
+      const name = n.expression.text;
+      if (ctx2.analyzer.jsxFunctions.has(name) || ctx2.analyzer.jsxMultiReturnFunctions.has(name)) {
+        found = true;
+        return;
+      }
+    }
+    ts11.forEachChild(n, visit3);
+  };
+  visit3(node);
+  return found;
+}
 function containsAwaitExpression(node) {
   if (ts11.isAwaitExpression(node)) return true;
   if (ts11.isFunctionDeclaration(node) || ts11.isFunctionExpression(node) || ts11.isArrowFunction(node)) return false;
@@ -7466,7 +7545,7 @@ function transformJsxExpression(expr, ctx2, isClientOnly = false) {
       if (node.operatorToken.kind === ts11.SyntaxKind.AmpersandAmpersandToken) {
         return transformLogicalAnd(node, ctx2);
       }
-      if ((node.operatorToken.kind === ts11.SyntaxKind.QuestionQuestionToken || node.operatorToken.kind === ts11.SyntaxKind.BarBarToken) && containsJsxInExpression(node.right)) {
+      if ((node.operatorToken.kind === ts11.SyntaxKind.QuestionQuestionToken || node.operatorToken.kind === ts11.SyntaxKind.BarBarToken) && (containsJsxInExpression(node.right) || callsJsxHelper(node.right, ctx2))) {
         return transformNullishCoalescing(node, ctx2);
       }
       return null;
@@ -7906,17 +7985,20 @@ function checkLoopKey(callback, ctx2, isNested) {
     body = ret.expression;
   }
   while (ts11.isParenthesizedExpression(body)) body = body.expression;
+  function checkJsxOperand(node) {
+    let n = node;
+    while (ts11.isParenthesizedExpression(n)) n = n.expression;
+    if (ts11.isJsxElement(n)) checkOpening(n.openingElement);
+    else if (ts11.isJsxSelfClosingElement(n)) checkOpening(n);
+  }
   if (ts11.isConditionalExpression(body)) {
-    const whenTrue = body.whenTrue;
-    const whenFalse = body.whenFalse;
-    let wt = whenTrue;
-    let wf = whenFalse;
-    while (ts11.isParenthesizedExpression(wt)) wt = wt.expression;
-    while (ts11.isParenthesizedExpression(wf)) wf = wf.expression;
-    if (ts11.isJsxElement(wt)) checkOpening(wt.openingElement);
-    else if (ts11.isJsxSelfClosingElement(wt)) checkOpening(wt);
-    if (ts11.isJsxElement(wf)) checkOpening(wf.openingElement);
-    else if (ts11.isJsxSelfClosingElement(wf)) checkOpening(wf);
+    checkJsxOperand(body.whenTrue);
+    checkJsxOperand(body.whenFalse);
+    return;
+  }
+  if (ts11.isBinaryExpression(body) && (body.operatorToken.kind === ts11.SyntaxKind.AmpersandAmpersandToken || body.operatorToken.kind === ts11.SyntaxKind.BarBarToken || body.operatorToken.kind === ts11.SyntaxKind.QuestionQuestionToken)) {
+    checkJsxOperand(body.left);
+    checkJsxOperand(body.right);
     return;
   }
   if (ts11.isJsxElement(body)) {
@@ -7938,6 +8020,39 @@ function loopBodyIsMultiRoot(children) {
   if (only.type !== "fragment") return false;
   return loopBodyIsMultiRoot(only.children);
 }
+function branchHasNoElement(node) {
+  if (node.type === "element" || node.type === "component") return false;
+  if (node.type === "conditional") {
+    return branchHasNoElement(node.whenTrue) || branchHasNoElement(node.whenFalse);
+  }
+  if (node.type === "fragment") {
+    const real = node.children.filter(
+      (c) => !(c.type === "text" && typeof c.value === "string" && !c.value.trim())
+    );
+    return real.length !== 1 || branchHasNoElement(real[0]);
+  }
+  return true;
+}
+function loopBodyItemConditional(children) {
+  const real = children.filter(
+    (c) => !(c.type === "text" && typeof c.value === "string" && !c.value.trim())
+  );
+  if (real.length !== 1) return null;
+  const only = real[0];
+  if (only.type !== "conditional") return null;
+  if (branchHasNoElement(only.whenTrue) || branchHasNoElement(only.whenFalse)) {
+    return only;
+  }
+  return null;
+}
+function extractItemConditionalKey(cond) {
+  const a = branchHasNoElement(cond.whenTrue) ? null : extractLoopKey(cond.whenTrue);
+  const b = branchHasNoElement(cond.whenFalse) ? null : extractLoopKey(cond.whenFalse);
+  if (a !== null && b !== null) {
+    return normalizeKeyExpr(a) === normalizeKeyExpr(b) ? a : null;
+  }
+  return a ?? b;
+}
 function transformMapCall(node, ctx2, isClientOnly = false, method = "map") {
   const isNested = ctx2.loopParams.size > 0;
   const propAccess = node.expression;
@@ -8134,6 +8249,16 @@ function transformMapCall(node, ctx2, isClientOnly = false, method = "map") {
       ctx2.loopParams.add(param);
     }
     if (index) ctx2.loopParams.add(index);
+    const tryTransformRenderableBody = (expr) => {
+      if (!ts11.isBinaryExpression(expr)) return;
+      const op = expr.operatorToken.kind;
+      if (op !== ts11.SyntaxKind.AmpersandAmpersandToken && op !== ts11.SyntaxKind.BarBarToken && op !== ts11.SyntaxKind.QuestionQuestionToken) {
+        return;
+      }
+      if (!containsJsxInExpression(expr) && !callsJsxHelper(expr, ctx2)) return;
+      const transformed = transformJsxExpression(expr, ctx2, isClientOnly);
+      if (transformed) children = [transformed];
+    };
     const body = callback.body;
     if (ts11.isJsxElement(body) || ts11.isJsxSelfClosingElement(body) || ts11.isJsxFragment(body)) {
       const transformed = transformNode(body, ctx2);
@@ -8156,6 +8281,8 @@ function transformMapCall(node, ctx2, isClientOnly = false, method = "map") {
         children = [transformConditional(inner, ctx2)];
       } else if (method === "flatMap" && ts11.isArrayLiteralExpression(inner)) {
         children = transformArrayLiteralChildren(inner, ctx2);
+      } else {
+        tryTransformRenderableBody(inner);
       }
     } else if (method === "flatMap" && ts11.isArrayLiteralExpression(body)) {
       children = transformArrayLiteralChildren(body, ctx2);
@@ -8203,6 +8330,8 @@ function transformMapCall(node, ctx2, isClientOnly = false, method = "map") {
       if (method === "flatMap" && children.length === 0) {
         flatMapCallback = buildFlatMapCallback(callback, body, ctx2);
       }
+    } else {
+      tryTransformRenderableBody(body);
     }
     if (paramBindings) {
       for (const b of paramBindings) ctx2.loopParams.delete(b.name);
@@ -8217,7 +8346,9 @@ function transformMapCall(node, ctx2, isClientOnly = false, method = "map") {
   if (ts11.isArrowFunction(node.arguments[0]) && children.length > 0) {
     checkLoopKey(node.arguments[0], ctx2, isNested);
   }
-  const key = children.length > 0 ? extractLoopKey(children[0]) : null;
+  const itemConditional = children.length > 0 ? loopBodyItemConditional(children) : null;
+  const bodyIsItemConditional = itemConditional !== null;
+  const key = bodyIsItemConditional ? extractItemConditionalKey(itemConditional) : children.length > 0 ? extractLoopKey(children[0]) : null;
   let childComponent;
   if (children.length === 1 && children[0].type === "component") {
     const comp = children[0];
@@ -8263,6 +8394,7 @@ function transformMapCall(node, ctx2, isClientOnly = false, method = "map") {
     callsReactiveGetters: callsReactive || void 0,
     hasFunctionCalls: hasCalls || void 0,
     bodyIsMultiRoot: bodyIsMultiRoot || void 0,
+    bodyIsItemConditional: bodyIsItemConditional || void 0,
     childComponent,
     nestedComponents,
     filterPredicate,
@@ -9433,7 +9565,8 @@ function collectLoopChildReactiveAttrs(node, ctx2, loopParam, loopParamBindings)
         const valueStr = attrValueToString(attr.value);
         if (!valueStr) continue;
         const expanded = expandConstantForReactivity(valueStr, ctx2, attr.freeIdentifiers);
-        if (!attr.clientOnly && classifyReactivity(expanded.expr, ctx2, loopParam, loopParamBindings, expanded.freeIds).kind === "none") continue;
+        const reactive = classifyReactivity(expanded.expr, ctx2, loopParam, loopParamBindings, expanded.freeIds).kind !== "none" || attr.callsReactiveGetters || attr.hasFunctionCalls;
+        if (!attr.clientOnly && !reactive) continue;
         attrs.push({
           childSlotId: el.slotId,
           attrName: attr.name,
@@ -9462,21 +9595,30 @@ function producesDomChild(node) {
 }
 function computeLoopSiblingOffsets(root) {
   const offsets = /* @__PURE__ */ new Map();
-  walkIR(root, null, {
-    element: ({ node: el, descend }) => {
-      let nonLoopCount = 0;
-      for (const child of el.children) {
-        if (child.type === "loop") {
-          if (nonLoopCount > 0) offsets.set(child, nonLoopCount);
-        } else if (producesDomChild(child)) {
-          nonLoopCount++;
-        }
+  const recordChildren = (children) => {
+    let nonLoopCount = 0;
+    for (const child of children) {
+      if (child.type === "loop") {
+        if (nonLoopCount > 0) offsets.set(child, nonLoopCount);
+      } else if (producesDomChild(child)) {
+        nonLoopCount++;
       }
-      descend();
     }
-    // All container kinds (fragment / component / provider / async / loop /
-    // conditional / if-statement) rely on walkIR's default descent with the
-    // same scope. Leaves (text / expression / slot) are no-ops.
+  };
+  const containerVisit = ({ node, descend }) => {
+    recordChildren(node.children);
+    descend();
+  };
+  walkIR(root, null, {
+    element: containerVisit,
+    component: containerVisit,
+    fragment: containerVisit,
+    provider: containerVisit,
+    async: containerVisit
+    // `loop` / `conditional` / `if-statement` are not flat sibling
+    // containers (their children are item bodies / branches), and leaves
+    // (text / expression / slot) have no children — all rely on walkIR's
+    // default descent with the same scope.
   });
   return offsets;
 }
@@ -9557,6 +9699,7 @@ function collectInnerLoops(nodes, siblingOffsets, outerLoopParam, ctx2, options)
           key: n.key,
           markerId: n.markerId,
           bodyIsMultiRoot: n.bodyIsMultiRoot,
+          bodyIsItemConditional: n.bodyIsItemConditional,
           iterationShape: n.iterationShape,
           containerSlotId: scope.parentSlotId,
           template,
@@ -9763,6 +9906,7 @@ function collectElements(node, ctx2, siblingOffsets, insideConditional = false)
         key: l.key,
         markerId: l.markerId,
         bodyIsMultiRoot: l.bodyIsMultiRoot,
+        bodyIsItemConditional: l.bodyIsItemConditional,
         iterationShape: l.iterationShape,
         template,
         staticItemTemplate,
@@ -9956,6 +10100,7 @@ function collectBranchLoops(node, ctx2, siblingOffsets) {
         key: n.key,
         markerId: n.markerId,
         bodyIsMultiRoot: n.bodyIsMultiRoot,
+        bodyIsItemConditional: n.bodyIsItemConditional,
         iterationShape: n.iterationShape,
         template: childTemplate,
         containerSlotId: containerSlot,
@@ -10624,6 +10769,7 @@ var init_imports = __esm({
       "getLoopChildren",
       "getLoopNodes",
       "mapArray",
+      "mapArrayAnchored",
       "createDisposableEffect",
       "createComponent",
       "renderChild",
@@ -10647,7 +10793,8 @@ var init_imports = __esm({
       "qsaChildScopes",
       "upsertChildItem",
       "__slot",
-      "__bfSlot"
+      "__bfSlot",
+      "__bfText"
     ];
     RUNTIME_MODULE = "@barefootjs/client/runtime";
     IMPORT_PLACEHOLDER = "/* __BAREFOOTJS_DOM_IMPORTS__ */";
@@ -13528,17 +13675,21 @@ function emitDynamicTextUpdates(lines, ctx2) {
     const conditionalElems = elems.filter((e) => e.insideConditional);
     const normalElems = elems.filter((e) => !e.insideConditional);
     if (normalElems.length > 0 || conditionalElems.length > 0) {
+      for (const elem of normalElems) {
+        const v = varSlotId(elem.slotId);
+        lines.push(`  let __anchor_${v} = _${v}`);
+      }
       lines.push(`  createEffect(() => {`);
       if (normalElems.length > 0) {
         lines.push(`    const __val = ${expr}`);
         for (const elem of normalElems) {
           const v = varSlotId(elem.slotId);
-          lines.push(`    if (_${v} && !__val?.__isSlot) _${v}.nodeValue = String(__val ?? '')`);
+          lines.push(`    __anchor_${v} = __bfText(__anchor_${v}, __val)`);
         }
         for (const elem of conditionalElems) {
           const v = varSlotId(elem.slotId);
           lines.push(`    const [__el_${v}] = $t(__scope, '${elem.slotId}')`);
-          lines.push(`    if (__el_${v} && !__val?.__isSlot) __el_${v}.nodeValue = String(__val ?? '')`);
+          lines.push(`    __bfText(__el_${v}, __val)`);
         }
       } else {
         lines.push(`    let __val`);
@@ -13546,7 +13697,7 @@ function emitDynamicTextUpdates(lines, ctx2) {
         for (const elem of conditionalElems) {
           const v = varSlotId(elem.slotId);
           lines.push(`    const [__el_${v}] = $t(__scope, '${elem.slotId}')`);
-          lines.push(`    if (__el_${v} && !__val?.__isSlot) __el_${v}.nodeValue = String(__val ?? '')`);
+          lines.push(`    __bfText(__el_${v}, __val)`);
         }
       }
       lines.push(`  })`);
@@ -14079,8 +14230,14 @@ function stringifyPlainLoop(lines, plan, topIndent = "  ") {
     template,
     reactiveEffects,
     childRefs,
-    bodyIsMultiRoot
+    bodyIsMultiRoot,
+    anchored,
+    anchorKeyExpr
   } = plan;
+  if (anchored) {
+    stringifyAnchoredLoop(lines, plan, topIndent, anchorKeyExpr);
+    return;
+  }
   if (reactiveEffects === null && !bodyIsMultiRoot && childRefs.length === 0) {
     const unwrapInline = paramUnwrap ? `${paramUnwrap} ` : "";
     const preamble = mapPreambleWrapped ? `${mapPreambleWrapped}; ` : "";
@@ -14107,6 +14264,39 @@ function stringifyPlainLoop(lines, plan, topIndent = "  ") {
   lines.push(`${bodyIndent}return __el`);
   lines.push(`${topIndent}}, '${markerId}')`);
 }
+function stringifyAnchoredLoop(lines, plan, topIndent, anchorKeyExpr) {
+  const {
+    containerVar,
+    markerId,
+    arrayExpr,
+    keyFn,
+    paramHead,
+    paramUnwrap,
+    indexParam,
+    mapPreambleWrapped,
+    reactiveEffects
+  } = plan;
+  const condSlot = reactiveEffects?.conditionals[0]?.slotId ?? null;
+  lines.push(`${topIndent}mapArrayAnchored(() => ${arrayExpr}, ${containerVar}, ${keyFn}, (${paramHead}, ${indexParam}, __existing) => {`);
+  const bodyIndent = topIndent + "  ";
+  if (paramUnwrap) lines.push(`${bodyIndent}${paramUnwrap}`);
+  if (mapPreambleWrapped) lines.push(`${bodyIndent}${mapPreambleWrapped}`);
+  lines.push(`${bodyIndent}const __anchor = __existing ?? document.createComment(\`bf-loop-i:\${${anchorKeyExpr}}\`)`);
+  lines.push(`${bodyIndent}let __frag = null`);
+  lines.push(`${bodyIndent}if (!__existing) {`);
+  lines.push(`${bodyIndent}  __frag = document.createDocumentFragment()`);
+  lines.push(`${bodyIndent}  __frag.appendChild(__anchor)`);
+  if (condSlot) {
+    lines.push(`${bodyIndent}  __frag.appendChild(document.createComment('bf-cond-start:${condSlot}'))`);
+    lines.push(`${bodyIndent}  __frag.appendChild(document.createComment('bf-cond-end:${condSlot}'))`);
+  }
+  lines.push(`${bodyIndent}}`);
+  if (reactiveEffects !== null) {
+    stringifyReactiveEffects(lines, reactiveEffects, { indent: bodyIndent, elVar: "__anchor", bodyIsMultiRoot: false });
+  }
+  lines.push(`${bodyIndent}return __frag ?? __anchor`);
+  lines.push(`${topIndent}}, '${markerId}')`);
+}
 function stringifyStaticLoop(lines, plan) {
   const { containerVar, arrayExpr, param, indexParam, childIndexExpr, attrsBySlot, texts, childRefs, csrMaterialize } = plan;
   const hasAttrs = attrsBySlot.length > 0;
@@ -14667,10 +14857,10 @@ function emitArmBody2(lines, body, mode, indent) {
   }
   for (const te of body.textEffects) {
     const v = varSlotId(te.slotId);
-    lines.push(`${indent}const [__el_${v}] = $t(__branchScope, '${te.slotId}')`);
+    lines.push(`${indent}let __anchor_${v} = $t(__branchScope, '${te.slotId}')[0]`);
     lines.push(`${indent}__disposers.push(createDisposableEffect(() => {`);
     lines.push(`${indent}  const __val = ${te.expression}`);
-    lines.push(`${indent}  if (__el_${v} && !__val?.__isSlot) __el_${v}.nodeValue = String(__val ?? '')`);
+    lines.push(`${indent}  __anchor_${v} = __bfText(__anchor_${v}, __val)`);
     lines.push(`${indent}}))`);
   }
   if (body.loops.length > 0) {
@@ -14767,6 +14957,9 @@ 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);
+  }
   if (elem.isStaticArray) {
     return buildStaticLoopPlan(elem, opts.unsafeLocalNames);
   }
@@ -14796,7 +14989,15 @@ function buildPlainLoopPlan(elem) {
     template: elem.template,
     reactiveEffects: hasReactive2 ? buildLoopReactiveEffectsPlan(elem) : null,
     childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
-    bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false
+    bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,
+    anchored: elem.bodyIsItemConditional ?? false,
+    // Fall back to the iteration index when the loop has no key. A whole-item
+    // conditional without a key is a BF023 error, but the emitted client JS
+    // must still parse — an empty `anchorKeyExpr` would produce
+    // `createComment(`bf-loop-i:${}`)` (a SyntaxError that breaks the whole
+    // bundle). `elem.index || '__idx'` matches `indexParam` above, so the
+    // anchor value stays consistent with the renderItem's own index param.
+    anchorKeyExpr: elem.key ? wrap(elem.key) : elem.index || "__idx"
   };
 }
 function buildStaticLoopPlan(elem, unsafeLocalNames) {
@@ -15888,17 +16089,23 @@ function runSinglePass(source, filePath, startingCounter) {
   }
   function visit3(node) {
     if (ts15.isJsxAttribute(node) && node.initializer && ts15.isJsxExpression(node.initializer) && node.initializer.expression) {
-      let expr = node.initializer.expression;
-      while (ts15.isParenthesizedExpression(expr)) expr = expr.expression;
-      if (ts15.isArrowFunction(expr) && arrowBodyContainsJsx(expr)) {
-        const handled = handleInlineArrow(expr);
-        if (handled) {
-          return;
-        }
+      if (tryHandleArrowValue(node.initializer.expression)) {
+        return;
       }
     }
+    if (ts15.isPropertyAssignment(node) && node.initializer) {
+      if (tryHandleArrowValue(node.initializer)) return;
+    }
     ts15.forEachChild(node, visit3);
   }
+  function tryHandleArrowValue(initializer) {
+    let expr = initializer;
+    while (ts15.isParenthesizedExpression(expr)) expr = expr.expression;
+    if (ts15.isArrowFunction(expr) && arrowBodyContainsJsx(expr)) {
+      return handleInlineArrow(expr);
+    }
+    return false;
+  }
   function handleInlineArrow(arrow) {
     const paramNames = collectArrowParamNames(arrow);
     const free = collectFreeIdentifiers(arrow);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "CLI for agent-driven UI component discovery and scaffolding",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
     "typescript": "^5.0.0"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.5.0",
+    "@barefootjs/jsx": "0.5.2",
     "@types/node": "^22.0.0"
   }
 }